Metadata-Version: 2.4
Name: inseq
Version: 0.7.1
Summary: Interpretability for Sequence Generation Models 🔍
Author: The Inseq Team
Author-email: info@inseq.org
Maintainer: Gabriele Sarti
Maintainer-email: gabriele.sarti996@gmail.com
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
            "License" shall mean the terms and conditions for use, reproduction, and
            distribution as defined by Sections 1 through 9 of this document.
        
            "Licensor" shall mean the copyright owner or entity authorized by the
            copyright owner that is granting the License.
        
            "Legal Entity" shall mean the union of the acting entity and all other
            entities that control, are controlled by, or are under common control with
            that entity. For the purposes of this definition, "control" means (i) the
            power, direct or indirect, to cause the direction or management of such
            entity, whether by contract or otherwise, or (ii) ownership of
            fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
            ownership of such entity.
        
            "You" (or "Your") shall mean an individual or Legal Entity exercising
            permissions granted by this License.
        
            "Source" form shall mean the preferred form for making modifications,
            including but not limited to software source code, documentation source,
            and configuration files.
        
            "Object" form shall mean any form resulting from mechanical transformation
            or translation of a Source form, including but not limited to compiled
            object code, generated documentation, and conversions to
            other media types.
        
            "Work" shall mean the work of authorship, whether in Source or Object
            form, made available under the License, as indicated by a copyright notice
            that is included in or attached to the work (an example is provided in the
            Appendix below).
        
            "Derivative Works" shall mean any work, whether in Source or Object form,
            that is based on (or derived from) the Work and for which the editorial
            revisions, annotations, elaborations, or other modifications represent,
            as a whole, an original work of authorship. For the purposes of this
            License, Derivative Works shall not include works that remain separable
            from, or merely link (or bind by name) to the interfaces of, the Work and
            Derivative Works thereof.
        
            "Contribution" shall mean any work of authorship, including the original
            version of the Work and any modifications or additions to that Work or
            Derivative Works thereof, that is intentionally submitted to Licensor for
            inclusion in the Work by the copyright owner or by an individual or
            Legal Entity authorized to submit on behalf of the copyright owner.
            For the purposes of this definition, "submitted" means any form of
            electronic, verbal, or written communication sent to the Licensor or its
            representatives, including but not limited to communication on electronic
            mailing lists, source code control systems, and issue tracking systems
            that are managed by, or on behalf of, the Licensor for the purpose of
            discussing and improving the Work, but excluding communication that is
            conspicuously marked or otherwise designated in writing by the copyright
            owner as "Not a Contribution."
        
            "Contributor" shall mean Licensor and any individual or Legal Entity on
            behalf of whom a Contribution has been received by Licensor and
            subsequently incorporated within the Work.
        
        2. Grant of Copyright License.
        
            Subject to the terms and conditions of this License, each Contributor
            hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
            royalty-free, irrevocable copyright license to reproduce, prepare
            Derivative Works of, publicly display, publicly perform, sublicense,
            and distribute the Work and such Derivative Works in
            Source or Object form.
        
        3. Grant of Patent License.
        
            Subject to the terms and conditions of this License, each Contributor
            hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
            royalty-free, irrevocable (except as stated in this section) patent
            license to make, have made, use, offer to sell, sell, import, and
            otherwise transfer the Work, where such license applies only to those
            patent claims licensable by such Contributor that are necessarily
            infringed by their Contribution(s) alone or by combination of their
            Contribution(s) with the Work to which such Contribution(s) was submitted.
            If You institute patent litigation against any entity (including a
            cross-claim or counterclaim in a lawsuit) alleging that the Work or a
            Contribution incorporated within the Work constitutes direct or
            contributory patent infringement, then any patent licenses granted to
            You under this License for that Work shall terminate as of the date such
            litigation is filed.
        
        4. Redistribution.
        
            You may reproduce and distribute copies of the Work or Derivative Works
            thereof in any medium, with or without modifications, and in Source or
            Object form, provided that You meet the following conditions:
        
            1. You must give any other recipients of the Work or Derivative Works a
            copy of this License; and
        
            2. You must cause any modified files to carry prominent notices stating
            that You changed the files; and
        
            3. You must retain, in the Source form of any Derivative Works that You
            distribute, all copyright, patent, trademark, and attribution notices from
            the Source form of the Work, excluding those notices that do not pertain
            to any part of the Derivative Works; and
        
            4. If the Work includes a "NOTICE" text file as part of its distribution,
            then any Derivative Works that You distribute must include a readable copy
            of the attribution notices contained within such NOTICE file, excluding
            those notices that do not pertain to any part of the Derivative Works,
            in at least one of the following places: within a NOTICE text file
            distributed as part of the Derivative Works; within the Source form or
            documentation, if provided along with the Derivative Works; or, within a
            display generated by the Derivative Works, if and wherever such
            third-party notices normally appear. The contents of the NOTICE file are
            for informational purposes only and do not modify the License.
            You may add Your own attribution notices within Derivative Works that You
            distribute, alongside or as an addendum to the NOTICE text from the Work,
            provided that such additional attribution notices cannot be construed
            as modifying the License.
        
            You may add Your own copyright statement to Your modifications and may
            provide additional or different license terms and conditions for use,
            reproduction, or distribution of Your modifications, or for any such
            Derivative Works as a whole, provided Your use, reproduction, and
            distribution of the Work otherwise complies with the conditions
            stated in this License.
        
        5. Submission of Contributions.
        
            Unless You explicitly state otherwise, any Contribution intentionally
            submitted for inclusion in the Work by You to the Licensor shall be under
            the terms and conditions of this License, without any additional
            terms or conditions. Notwithstanding the above, nothing herein shall
            supersede or modify the terms of any separate license agreement you may
            have executed with Licensor regarding such Contributions.
        
        6. Trademarks.
        
            This License does not grant permission to use the trade names, trademarks,
            service marks, or product names of the Licensor, except as required for
            reasonable and customary use in describing the origin of the Work and
            reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty.
        
            Unless required by applicable law or agreed to in writing, Licensor
            provides the Work (and each Contributor provides its Contributions)
            on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
            either express or implied, including, without limitation, any warranties
            or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS
            FOR A PARTICULAR PURPOSE. You are solely responsible for determining the
            appropriateness of using or redistributing the Work and assume any risks
            associated with Your exercise of permissions under this License.
        
        8. Limitation of Liability.
        
            In no event and under no legal theory, whether in tort
            (including negligence), contract, or otherwise, unless required by
            applicable law (such as deliberate and grossly negligent acts) or agreed
            to in writing, shall any Contributor be liable to You for damages,
            including any direct, indirect, special, incidental, or consequential
            damages of any character arising as a result of this License or out of
            the use or inability to use the Work (including but not limited to damages
            for loss of goodwill, work stoppage, computer failure or malfunction,
            or any and all other commercial damages or losses), even if such
            Contributor has been advised of the possibility of such damages.
        
        9. Accepting Warranty or Additional Liability.
        
            While redistributing the Work or Derivative Works thereof, You may choose
            to offer, and charge a fee for, acceptance of support, warranty,
            indemnity, or other liability obligations and/or rights consistent with
            this License. However, in accepting such obligations, You may act only
            on Your own behalf and on Your sole responsibility, not on behalf of any
            other Contributor, and only if You agree to indemnify, defend, and hold
            each Contributor harmless for any liability incurred by, or claims
            asserted against, such Contributor by reason of your accepting any such
            warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
        
        APPENDIX: How to apply the Apache License to your work
        
            To apply the Apache License to your work, attach the following boilerplate
            notice, with the fields enclosed by brackets "[]" replaced with your own
            identifying information. (Don't include the brackets!) The text should be
            enclosed in the appropriate comment syntax for the file format. We also
            recommend that a file or class name and description of purpose be included
            on the same "printed page" as the copyright notice for easier
            identification within third-party archives.
        
                Copyright 2021 The Inseq Team
                
                Licensed under the Apache License, Version 2.0 (the "License");
                you may not use this file except in compliance with the License.
                You may obtain a copy of the License at
        
                http://www.apache.org/licenses/LICENSE-2.0
        
                Unless required by applicable law or agreed to in writing, software
                distributed under the License is distributed on an "AS IS" BASIS,
                WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
                or implied. See the License for the specific language governing
                permissions and limitations under the License.
Project-URL: homepage, https://github.com/inseq-team/inseq
Project-URL: documentation, https://inseq.org
Project-URL: repository, https://github.com/inseq-team/inseq
Project-URL: changelog, https://github.com/inseq-team/inseq/blob/main/CHANGELOG.md
Keywords: generative AI,transformers,natural language processing,XAI,explainable ai,interpretability,feature attribution,machine translation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: GPU
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=10.13.0
Requires-Dist: transformers[sentencepiece,tokenizers]>=4.53.0
Requires-Dist: captum>=0.7.0
Requires-Dist: jaxtyping>=0.2.25
Requires-Dist: typeguard<=2.13.3
Requires-Dist: matplotlib>=3.5.3
Requires-Dist: tqdm>=4.64.0
Requires-Dist: treescope>=0.1.0
Requires-Dist: nvidia-cublas-cu11>=11.10.3.66; sys_platform == "Linux"
Requires-Dist: nvidia-cuda-cupti-cu11>=11.7.101; sys_platform == "Linux"
Requires-Dist: nvidia-cuda-nvrtc-cu11>=11.7.99; sys_platform == "Linux"
Requires-Dist: nvidia-cuda-runtime-cu11>=11.7.99; sys_platform == "Linux"
Requires-Dist: nvidia-cudnn-cu11>=8.5.0.96; sys_platform == "Linux"
Requires-Dist: nvidia-cufft-cu11>=10.9.0.58; sys_platform == "Linux"
Requires-Dist: nvidia-curand-cu11>=10.2.10.91; sys_platform == "Linux"
Requires-Dist: nvidia-cusolver-cu11>=11.4.0.1; sys_platform == "Linux"
Requires-Dist: nvidia-cusparse-cu11>=11.7.4.91; sys_platform == "Linux"
Requires-Dist: nvidia-nccl-cu11>=2.14.3; sys_platform == "Linux"
Requires-Dist: nvidia-nvtx-cu11>=11.7.91; sys_platform == "Linux"
Requires-Dist: protobuf>=4.25.8
Requires-Dist: urllib3>=2.6.0
Requires-Dist: tornado>=6.5.0
Requires-Dist: setuptools>=78.1.1
Requires-Dist: requests>=2.32.4
Requires-Dist: regex>=2025.2.10
Requires-Dist: jinja2>=3.1.5
Requires-Dist: cryptography>=44.0.1
Requires-Dist: aiohttp>=3.12.14
Requires-Dist: authlib>=1.6.5
Requires-Dist: marshmallow!=4.0.0,!=4.0.1,!=4.1.0,!=4.1.1,>=3.26.2
Requires-Dist: fonttools>=4.61.0
Requires-Dist: filelock>=3.20.1
Provides-Extra: docs
Requires-Dist: sphinx>=5.3.0; extra == "docs"
Requires-Dist: sphinxemoji>=0.2.0; extra == "docs"
Requires-Dist: sphinxext-opengraph>=0.4.2; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.4.0; extra == "docs"
Requires-Dist: sphinx-gitstamp>=0.3.2; extra == "docs"
Requires-Dist: sphinx-design>=0.4.1; extra == "docs"
Requires-Dist: furo>=2022.12.7; extra == "docs"
Provides-Extra: lint
Requires-Dist: bandit>=1.7.4; extra == "lint"
Requires-Dist: safety>=3.1.0; extra == "lint"
Requires-Dist: pydoclint>=0.4.0; extra == "lint"
Requires-Dist: pre-commit>=3.20.0; extra == "lint"
Requires-Dist: pytest>=7.2.0; extra == "lint"
Requires-Dist: pytest-cov>=4.0.0; extra == "lint"
Requires-Dist: pytest-xdist>=3.5.0; extra == "lint"
Requires-Dist: ruff>=0.13.0; extra == "lint"
Requires-Dist: virtualenv>=20.26.6; extra == "lint"
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.5.1; extra == "sklearn"
Requires-Dist: joblib>=1.3.2; extra == "sklearn"
Provides-Extra: datasets
Requires-Dist: datasets>=2.17.0; extra == "datasets"
Provides-Extra: notebook
Requires-Dist: ipykernel>=6.29.2; extra == "notebook"
Requires-Dist: ipywidgets>=8.1.2; extra == "notebook"
Provides-Extra: nltk
Requires-Dist: nltk>=3.8.1; extra == "nltk"
Dynamic: license-file

<div align="center">
  <img src="https://raw.githubusercontent.com/inseq-team/inseq/main/docs/source/images/inseq_logo.png" width="300"/>
  <h4>Intepretability for Sequence Generation Models 🔍</h4>
</div>
<br/>
<div align="center">


[![Build status](https://img.shields.io/github/actions/workflow/status/inseq-team/inseq/build.yml?branch=main)](https://github.com/inseq-team/inseq/actions?query=workflow%3Abuild)
[![Docs status](https://img.shields.io/readthedocs/inseq)](https://inseq.readthedocs.io)
[![Version](https://img.shields.io/pypi/v/inseq?color=blue)](https://pypi.org/project/inseq/)
[![Python Version](https://img.shields.io/pypi/pyversions/inseq.svg?color=blue)](https://pypi.org/project/inseq/)
[![Downloads](https://static.pepy.tech/badge/inseq)](https://pepy.tech/project/inseq)
[![License](https://img.shields.io/github/license/inseq-team/inseq)](https://github.com/inseq-team/inseq/blob/main/LICENSE)
[![Demo Paper](https://img.shields.io/badge/ACL%20Anthology%20-%20?logo=data%3Aimage%2Fx-icon%3Bbase64%2CAAABAAEAIBIAAAEAIABwCQAAFgAAACgAAAAgAAAAJAAAAAEAIAAAAAAAAAkAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACEa7k0mH%2B%2F5JBzt%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJB3t%2FyQd7f8kHe3%2FJBzt%2FyQc7f8kHO3%2FJBzt%2FyQd7f8kHO3%2FJB3t%2FyQd7f8kHO3%2FJB3t%2FyQd7f8kHe3%2FJB3t%2FyMc79EkGP8VAAAAAAAAAAAAAAAAIRruTSYf7%2FkkHO3%2FJBzt%2FyQd7f8kHe3%2FJB3t%2FyQd7f8kHO3%2FJB3t%2FyQc7f8kHe3%2FJBzt%2FyQc7f8kHO3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJB3t%2FyQc7f8kHO3%2FJB3t%2FyQd7f8kHe3%2FIxzv0SQY%2FxUAAAAAAAAAAAAAAAAhIe5NJh%2Fv%2BSQd7f8kHe3%2FJB3t%2FyQd7f8kHO3%2FJBzt%2FyQc7f8kHe3%2FJBzt%2FyQd7f8kHe3%2FJBzt%2FyQc7f8kHe3%2FJB3t%2FyQd7f8kHe3%2FJB3t%2FyQc7f8kHe3%2FJB3t%2FyQd7f8kHe3%2FJBzt%2FyQd7f8jHO%2FRJBj%2FFQAAAAAAAAAAAAAAACEa7k0mH%2B%2F5JB3t%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHe3%2FJBzt%2FyQd7f8kHe3%2FJBzt%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHe3%2FJBzt%2FyQd7f8kHe3%2FJB3t%2FyQc7f8kHe3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyMc79EkGP8VAAAAAAAAAAAAAAAAIRruTSYf7%2FkkHO3%2FJBzt%2FyQc7f8kHe3%2FJB3t%2FyQd7f8kHO3%2FJB3t%2FyQd7f8kHO3%2FJB3t%2FyQc7f8kHe3%2FJBzt%2FyQc7f8kHe3%2FJB3t%2FyQd7f8kHe3%2FJBzt%2FyQd7f8kHO3%2FJB3t%2FyQc7f8kHO3%2FIxzv0SQY%2FxUAAAAAAAAAAAAAAAAhGu5NJh%2Fv%2BSQd7f8kHO3%2FJBzt%2FyQd7f8jIOzYIxvtgiQc8X8kHPF%2FJBzxfyQc8X8kHPF%2FJBzxfyQc8X8kHPF%2FIx%2FuiiMf7OgkHe3%2FJBzt%2FyQc7f8kHO3%2FJhzs9CUg7JYkHPF%2FJBzxfyQc8X8iHfBoMzP%2FCgAAAAAAAAAAAAAAACEa7k0mHu%2F5JBzt%2FyQc7f8kHO3%2FJBzt%2FyQb7LEAAP8FAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAkGP8VIxzv0SQc7f8kHe3%2FJB3t%2FyQc7f8jHOzpIhzuLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIRruTSYf7%2FkkHe3%2FJB3t%2FyQd7f8kHO3%2FJBvssQAA%2FwUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACQY%2FxUjHO%2FRJB3t%2FyQc7f8kHO3%2FJBzt%2FyMb7OkiHO4tAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAhGu5NJh%2Fv%2BSQd7f8kHe3%2FJBzt%2FyQc7f8kHuyxAAD%2FBQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJBj%2FFSMc79EkHe3%2FJBzt%2FyQc7f8kHO3%2FIxvs6SIc7i0AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACEa7k0mH%2B%2F5JBzt%2FyQc7f8kHO3%2FJBzt%2FyQb7LEAAP8FAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAkGP8VIx3v0SQd7f8kHe3%2FJBzt%2FyQc7f8jHOzpIhzuLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIRruTSYf7%2FkkHO3%2FJBzt%2FyQc7f8kHe3%2FJBzuxSgi81MhGu5NIRruTSEa7k0hGu5NISHuTSEh7k0hGu5NIRruTSIa72EjHe3aJBzt%2FyQd7f8kHO3%2FJBzt%2FyMc7OkiHO4tAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAhGu5NJh7v%2BSQc7f8kHe3%2FJBzt%2FyQc7f8kHO3%2FJh%2Fv%2BSYf7%2FkmHu%2F5Jh%2Fv%2BSYf7%2FkmH%2B%2F5Jh%2Fv%2BSYf7%2FkmH%2B%2F5Jh7v%2BSQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FIxzs6SIc7i0AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACEa7k0mHu%2F5JBzt%2FyQd7f8kHO3%2FJBzt%2FyQc7f8kHe3%2FJB3t%2FyQd7f8kHO3%2FJBzt%2FyQc7f8kHe3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHe3%2FJBzt%2FyQd7f8jHOzpIhzuLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIRruTSYe7%2FkkHO3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyQd7f8kHe3%2FJB3t%2FyQc7f8kHe3%2FJB3t%2FyQd7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyMc7OkiHO4tAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAhGu5NJh%2Fv%2BSQc7f8kHO3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FIxzs6SIc7i0AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACEa7k0mH%2B%2F5JB3t%2FyQc7f8kHe3%2FJBzt%2FyQc7f8kHO3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyQd7f8kHO3%2FJBzt%2FyQc7f8kHO3%2FJB3t%2FyQc7f8kHO3%2FJBzt%2FyQc7f8jHOzpIhzuLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKB%2FtOSUc7askHuyxJBvssSQe7LEkHuyxJB7ssSQe7LEkHuyxJBvssSQb7LEkHuyxJB7ssSQe7LEkHuyxJB7ssSUc7LMjHe31JB3t%2FyQd7f8kHe3%2FJBzt%2FyMc7OkiHO4tAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD%2FBQAA%2FwUAAP8FAAD%2FBQAA%2FwUAAP8FAAD%2FBQAA%2FwUAAP8FAAD%2FBQAA%2FwUAAP8FAAD%2FBQAA%2FwUAAP8FHBzsGyMd7qYjHO%2FRIxzv0SMd79EjHO%2FRIx7tux4Y%2BSoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAAAABwAAAAcAAAAHAAAABwAAAAcAAAAHAP8A%2FwD%2FAP8A%2FwD%2FAP8A%2FwAAAP8AAAD%2FAAAA%2FwAAAP8AAAD%2FAAAA%2FwAAAP%2BAAAD8%3D&labelColor=white&color=red&link=https%3A%2F%2Faclanthology.org%2F2023.acl-demo.40%2F
)](https://aclanthology.org/2023.acl-demo.40)

</div>
<div align="center">

  [![Follow Inseq on Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://twitter.com/InseqLib)
  [![Join the Inseq Discord server](https://img.shields.io/badge/Discord-7289DA?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/V5VgwwFPbu)
  [![Read the Docs](https://img.shields.io/badge/-Docs-blue?style=for-the-badge&logo=Read-the-Docs&logoColor=white&link=https://inseq.org)](https://inseq.org)
  [![Tutorial](https://img.shields.io/badge/-Tutorial-orange?style=for-the-badge&logo=Jupyter&logoColor=white&link=https://github.com/inseq-team/inseq/blob/main/examples/inseq_tutorial.ipynb)](https://github.com/inseq-team/inseq/blob/main/examples/inseq_tutorial.ipynb)


</div>

Inseq is a Pytorch-based hackable toolkit to democratize access to common post-hoc **in**terpretability analyses of **seq**uence generation models.

## Installation

Inseq is available on PyPI and can be installed with `pip` for Python >= 3.10, <= 3.13:

```bash
# Install latest stable version
pip install inseq

# Alternatively, install latest development version
pip install git+https://github.com/inseq-team/inseq.git
```

Install extras for visualization in Jupyter Notebooks and 🤗 datasets attribution as `pip install inseq[notebook,datasets]`.

<details>
  <summary>Dev Installation</summary>
To install the package, clone the repository and run the following commands:

```bash
cd inseq
make uv-download # Download and install the uv package manager
make install # Installs the package and all dependencies via uv sync
```

For library developers, you can use the `make install-dev` command to install all development dependencies (quality, docs, extras).

After installation, you should be able to run `make fast-test` and `make lint` without errors.
</details>

<details>
  <summary>FAQ Installation</summary>

- Installing the `tokenizers` package requires a Rust compiler installation. You can install Rust from [https://rustup.rs](https://rustup.rs) and add `$HOME/.cargo/env` to your PATH.

- Installing `sentencepiece` requires various packages, install with `sudo apt-get install cmake build-essential pkg-config` or `brew install cmake gperftools pkg-config`.

</details>

## Example usage in Python

This example uses the Integrated Gradients attribution method to attribute the English-French translation of a sentence taken from the WinoMT corpus:

```python
import inseq

model = inseq.load_model("Helsinki-NLP/opus-mt-en-fr", "integrated_gradients")
out = model.attribute(
  "The developer argued with the designer because her idea cannot be implemented.",
  n_steps=100
)
out.show()
```

This produces a visualization of the attribution scores for each token in the input sentence (token-level aggregation is handled automatically). Here is what the visualization looks like inside a Jupyter Notebook:

![WinoMT Attribution Map](https://raw.githubusercontent.com/inseq-team/inseq/main/docs/source/images/heatmap_winomt.png)

Inseq also supports decoder-only models such as [GPT-2](https://huggingface.co/transformers/model_doc/gpt2.html), enabling usage of a variety of attribution methods and customizable settings directly from the console:

```python
import inseq

model = inseq.load_model("gpt2", "integrated_gradients")
model.attribute(
    "Hello ladies and",
    generation_args={"max_new_tokens": 9},
    n_steps=500,
    internal_batch_size=50
).show()
```

![GPT-2 Attribution in the console](https://raw.githubusercontent.com/inseq-team/inseq/main/docs/source/images/inseq_python_console.gif)

## Features

- 🚀 Feature attribution of sequence generation for most `ForConditionalGeneration` (encoder-decoder) and `ForCausalLM` (decoder-only) models from 🤗 Transformers

- 🚀 Support for multiple feature attribution methods, extending the ones supported by [Captum](https://captum.ai/docs/introduction)

- 🚀 Post-processing, filtering and merging of attribution maps via `Aggregator` classes.

- 🚀 Attribution visualization in notebooks, browser and command line.

- 🚀 Efficient attribution of single examples or entire 🤗 datasets with the Inseq CLI.

- 🚀 Custom attribution of target functions, supporting advanced methods such as [contrastive feature attributions](https://aclanthology.org/2022.emnlp-main.14/) and [context reliance detection](https://arxiv.org/abs/2310.01188).

- 🚀 Extraction and visualization of custom scores (e.g. probability, entropy) at every generation step alongsides attribution maps.

### Supported methods

Use the `inseq.list_feature_attribution_methods` function to list all available method identifiers and `inseq.list_step_functions` to list all available step functions. The following methods are currently supported:

#### Gradient-based attribution

- `saliency`: [Deep Inside Convolutional Networks: Visualising Image Classification Models and Saliency Maps](https://arxiv.org/abs/1312.6034) (Simonyan et al., 2013)

- `input_x_gradient`: [Deep Inside Convolutional Networks: Visualising Image Classification Models and Saliency Maps](https://arxiv.org/abs/1312.6034) (Simonyan et al., 2013)

- `integrated_gradients`: [Axiomatic Attribution for Deep Networks](https://arxiv.org/abs/1703.01365) (Sundararajan et al., 2017)

- `deeplift`: [Learning Important Features Through Propagating Activation Differences](https://arxiv.org/abs/1704.02685) (Shrikumar et al., 2017)

- `gradient_shap`: [A unified approach to interpreting model predictions](https://dl.acm.org/doi/10.5555/3295222.3295230) (Lundberg and Lee, 2017)

- `discretized_integrated_gradients`: [Discretized Integrated Gradients for Explaining Language Models](https://aclanthology.org/2021.emnlp-main.805/) (Sanyal and Ren, 2021)

- `sequential_integrated_gradients`: [Sequential Integrated Gradients: a simple but effective method for explaining language models](https://aclanthology.org/2023.findings-acl.477/) (Enguehard, 2023)

#### Internals-based attribution

- `attention`: Attention Weight Attribution, from [Neural Machine Translation by Jointly Learning to Align and Translate](https://arxiv.org/abs/1409.0473) (Bahdanau et al., 2014)

#### Perturbation-based attribution

- `occlusion`: [Visualizing and Understanding Convolutional Networks](https://link.springer.com/chapter/10.1007/978-3-319-10590-1_53) (Zeiler and Fergus, 2014)

- `lime`: ["Why Should I Trust You?": Explaining the Predictions of Any Classifier](https://arxiv.org/abs/1602.04938) (Ribeiro et al., 2016)

- `value_zeroing`: [Quantifying Context Mixing in Transformers](https://aclanthology.org/2023.eacl-main.245/) (Mohebbi et al. 2023)

- `reagent`: [ReAGent: A Model-agnostic Feature Attribution Method for Generative Language Models](https://arxiv.org/abs/2402.00794) (Zhao et al., 2024)

#### Step functions

Step functions are used to extract custom scores from the model at each step of the attribution process with the `step_scores` argument in `model.attribute`. They can also be used as targets for attribution methods relying on model outputs (e.g. gradient-based methods) by passing them as the `attributed_fn` argument. The following step functions are currently supported:

- `logits`: Logits of the target token.
- `probability`: Probability of the target token. Can also be used for log-probability by passing `logprob=True`.
- `entropy`: Entropy of the predictive distribution.
- `crossentropy`: Cross-entropy loss between target token and predicted distribution.
- `perplexity`: Perplexity of the target token.
- `contrast_logits`/`contrast_prob`: Logits/probabilities of the target token when different contrastive inputs are provided to the model. Equivalent to `logits`/`probability` when no contrastive inputs are provided.
- `contrast_logits_diff`/`contrast_prob_diff`: Difference in logits/probability between original and foil target tokens pair, can be used for contrastive evaluation as in [contrastive attribution](https://aclanthology.org/2022.emnlp-main.14/) (Yin and Neubig, 2022).
- `pcxmi`: Point-wise Contextual Cross-Mutual Information (P-CXMI) for the target token given original and contrastive contexts [(Yin et al. 2021)](https://arxiv.org/abs/2109.07446).
- `kl_divergence`: KL divergence of the predictive distribution given original and contrastive contexts. Can be restricted to most likely target token options using the `top_k` and `top_p` parameters.
- `in_context_pvi`: In-context Pointwise V-usable Information (PVI) to measure the amount of contextual information used in model predictions [(Lu et al. 2023)](https://arxiv.org/abs/2310.12300).
- `mc_dropout_prob_avg`: Average probability of the target token across multiple samples using [MC Dropout](https://arxiv.org/abs/1506.02142) (Gal and Ghahramani, 2016).
- `top_p_size`: The number of tokens with cumulative probability greater than `top_p` in the predictive distribution of the model.

The following example computes contrastive attributions using the `contrast_prob_diff` step function:

```python
import inseq

attribution_model = inseq.load_model("gpt2", "input_x_gradient")

# Perform the contrastive attribution:
# Regular (forced) target -> "The manager went home because he was sick"
# Contrastive target      -> "The manager went home because she was sick"
out = attribution_model.attribute(
    "The manager went home because",
    "The manager went home because he was sick",
    attributed_fn="contrast_prob_diff",
    contrast_targets="The manager went home because she was sick",
    # We also visualize the corresponding step score
    step_scores=["contrast_prob_diff"]
)
out.show()
```

Refer to the [documentation](https://inseq.readthedocs.io/examples/custom_attribute_target.html) for an example including custom function registration.

## Using the Inseq CLI

The Inseq library also provides useful client commands to enable repeated attribution of individual examples and even entire 🤗 datasets directly from the console. See the available options by typing `inseq -h` in the terminal after installing the package.

Three commands are supported:

- `inseq attribute`: Wrapper for enabling `model.attribute` usage in console.

- `inseq attribute-dataset`: Extends `attribute` to full dataset using Hugging Face `datasets.load_dataset` API.

- `inseq attribute-context`: Detects and attribute context dependence for generation tasks using the approach of [Sarti et al. (2023)](https://arxiv.org/abs/2310.01188).

All commands support the full range of parameters available for `attribute`, attribution visualization in the console and saving outputs to disk.

<details>
  <summary><code>inseq attribute</code> example</summary>

  The following example performs a simple feature attribution of an English sentence translated into Italian using a MarianNMT translation model from <code>transformers</code>. The final result is printed to the console.
  ```bash
  inseq attribute \
  --model_name_or_path Helsinki-NLP/opus-mt-en-it \
  --attribution_method saliency \
  --input_texts "Hello world this is Inseq\! Inseq is a very nice library to perform attribution analysis"
  ```

</details>

<details>
  <summary><code>inseq attribute-dataset</code> example</summary>

  The following code can be used to perform attribution (both source and target-side) of Italian translations for a dummy sample of 20 English sentences taken from the FLORES-101 parallel corpus, using a MarianNMT translation model from Hugging Face <code>transformers</code>. We save the visualizations in HTML format in the file <code>attributions.html</code>. See the <code>--help</code> flag for more options.

  ```bash
  inseq attribute-dataset \
    --model_name_or_path Helsinki-NLP/opus-mt-en-it \
    --attribution_method saliency \
    --do_prefix_attribution \
    --dataset_name inseq/dummy_enit \
    --input_text_field en \
    --dataset_split "train[:20]" \
    --viz_path attributions.html \
    --batch_size 8 \
    --hide
  ```
</details>

<details>
  <summary><code>inseq attribute-context</code> example</summary>

  The following example uses a small LM to generate a continuation of <code>input_current_text</code>, and uses the additional context provided by <code>input_context_text</code> to estimate its influence on the the generation. In this case, the output <code>"to the hospital. He said he was fine"</code> is produced, and the generation of token <code>hospital</code> is found to be dependent on context token <code>sick</code> according to the <code>contrast_prob_diff</code> step function.

  ```bash
  inseq attribute-context \
    --model_name_or_path HuggingFaceTB/SmolLM-135M \
    --input_context_text "George was sick yesterday." \
    --input_current_text "His colleagues asked him to come" \
    --attributed_fn "contrast_prob_diff"
  ```

  **Result:**

  <img src="https://raw.githubusercontent.com/inseq-team/inseq/main/docs/source/images/attribute_context_hospital_output.png" style="width:500px">
</details>

## Contributing

Our vision for Inseq is to create a centralized, comprehensive and robust set of tools to enable fair and reproducible comparisons in the study of sequence generation models. To achieve this goal, contributions from researchers and developers interested in these topics are more than welcome. Please see our [contributing guidelines](CONTRIBUTING.md) and our [code of conduct](CODE_OF_CONDUCT.md) for more information.

## Citing Inseq

If you use Inseq in your research we suggest including a mention of the specific release (e.g. v0.6.0) and we kindly ask you to cite our reference paper as:

```bibtex
@inproceedings{sarti-etal-2023-inseq,
    title = "Inseq: An Interpretability Toolkit for Sequence Generation Models",
    author = "Sarti, Gabriele  and
      Feldhus, Nils  and
      Sickert, Ludwig  and
      van der Wal, Oskar and
      Nissim, Malvina and
      Bisazza, Arianna",
    booktitle = "Proceedings of the 61st Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations)",
    month = jul,
    year = "2023",
    address = "Toronto, Canada",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2023.acl-demo.40",
    doi = "10.18653/v1/2023.acl-demo.40",
    pages = "421--435",
}
```

## Research using Inseq

Inseq has been used in various research projects. A list of known publications that use Inseq to conduct interpretability analyses of generative models is shown below.

> [!TIP]
> Last update: August 2024. Please open a pull request to add your publication to the list.

<details>
  <summary><b>2023</b></summary>
  <ol>
    <li> <a href="https://aclanthology.org/2023.acl-demo.40/">Inseq: An Interpretability Toolkit for Sequence Generation Models</a> (Sarti et al., 2023) </li>
    <li> <a href="https://doi.org/10.1162/tacl_a_00651">Are Character-level Translations Worth the Wait? Comparing ByT5 and mT5 for Machine Translation</a> (Edman et al., 2023) </li>
    <li> <a href="https://aclanthology.org/2023.nlp4convai-1.1/">Response Generation in Longitudinal Dialogues: Which Knowledge Representation Helps?</a> (Mousavi et al., 2023)  </li>
    <li> <a href="https://openreview.net/forum?id=XTHfNGI3zT">Quantifying the Plausibility of Context Reliance in Neural Machine Translation</a> (Sarti et al., 2023)</li>
    <li> <a href="https://aclanthology.org/2023.emnlp-main.243/">A Tale of Pronouns: Interpretability Informs Gender Bias Mitigation for Fairer Instruction-Tuned Machine Translation</a> (Attanasio et al., 2023)</li>
    <li> <a href="https://aclanthology.org/2023.conll-1.18/">Attribution and Alignment: Effects of Local Context Repetition on Utterance Production and Comprehension in Dialogue</a> (Molnar et al., 2023)</li>
  </ol>

</details>

<details>
  <summary><b>2024</b></summary>
  <ol>
    <li> <a href="https://aclanthology.org/2024.naacl-long.46/">Assessing the Reliability of Large Language Model Knowledge</a> (Wang et al., 2024)</li>
    <li><a href="https://aclanthology.org/2024.hcinlp-1.9">LLMCheckup: Conversational Examination of Large Language Models via Interpretability Tools</a> (Wang et al., 2024)</li>
    <li><a href="https://arxiv.org/abs/2402.00794">ReAGent: A Model-agnostic Feature Attribution Method for Generative Language Models</a> (Zhao et al., 2024)</li>
    <li><a href="https://aclanthology.org/2024.naacl-long.284">Revisiting subword tokenization: A case study on affixal negation in large language models</a> (Truong et al., 2024)</li>
    <li><a href="https://hal.science/hal-04581586">Exploring NMT Explainability for Translators Using NMT Visualising Tools</a> (Gonzalez-Saez et al., 2024)</li>
    <li><a href="https://openreview.net/forum?id=uILj5HPrag">DETAIL: Task DEmonsTration Attribution for Interpretable In-context Learning</a> (Zhou et al., 2024)</li>
    <li><a href="https://arxiv.org/abs/2406.06399">Should We Fine-Tune or RAG? Evaluating Different Techniques to Adapt LLMs for Dialogue</a> (Alghisi et al., 2024)</li>
    <li><a href="https://arxiv.org/abs/2406.13663">Model Internals-based Answer Attribution for Trustworthy Retrieval-Augmented Generation</a> (Qi, Sarti et al., 2024)</li>
    <li><a href="https://link.springer.com/chapter/10.1007/978-3-031-63787-2_14">NoNE Found: Explaining the Output of Sequence-to-Sequence Models When No Named Entity Is Recognized</a> (dela Cruz et al., 2024)</li>
    <li><a href="https://dl.acm.org/doi/full/10.1145/3701268.3701274">Reimagining Student Success Prediction: Applying LLMs in Educational AI with XAI</a> (Riello et al., 2024)</li>
  </ol>

</details>

<details>
  <summary><b>2025</b></summary>
  <ol>
    <li> <a href="https://aclanthology.org/2025.findings-naacl.390/">Reinforcement Learning for Aligning Large Language Models Agents with Interactive Environments: Quantifying and Mitigating Prompt Overfitting</a> (Aissi et al., 2025)</li>
    <li> <a href="https://dl.acm.org/doi/full/10.1145/3729237">Towards AI-Assisted Inclusive Language Writing in Italian Formal Communications</a> (Greco et al. 2025)</li>
    <li> <a href="https://arxiv.org/abs/2508.08661">Hallucinations in Code Change to Natural Language Generation: Prevalence and Evaluation of Detection Metrics</a> (Liu et al. 2025)</li>
    <li> <a href="https://arxiv.org/abs/2503.05810">A Transformer Model for Predicting Chemical Reaction Products from Generic Templates</a> (Ozer et al. 2025)</li>
  </ol>

</details>
