{"id":33108188,"url":"https://github.com/g8a9/ferret","last_synced_at":"2026-04-09T00:35:20.701Z","repository":{"id":37977140,"uuid":"497883806","full_name":"g8a9/ferret","owner":"g8a9","description":"A python package for benchmarking interpretability techniques on Transformers.","archived":false,"fork":false,"pushed_at":"2024-09-29T18:26:21.000Z","size":1590,"stargazers_count":212,"open_issues_count":15,"forks_count":17,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-11-15T02:03:17.460Z","etag":null,"topics":["benchmarking","interpretability","machine-learning","transformers"],"latest_commit_sha":null,"homepage":"https://ferret.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/g8a9.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-30T09:56:15.000Z","updated_at":"2025-10-27T03:33:06.000Z","dependencies_parsed_at":"2023-11-16T16:05:24.590Z","dependency_job_id":"484ce2ea-3882-480b-a40b-9916b7e6ae74","html_url":"https://github.com/g8a9/ferret","commit_stats":{"total_commits":235,"total_committers":3,"mean_commits":78.33333333333333,"dds":"0.28510638297872337","last_synced_commit":"59deec0ac171469e4a9aee9df56aebdcc466ba7e"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/g8a9/ferret","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fferret","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fferret/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fferret/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fferret/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/g8a9","download_url":"https://codeload.github.com/g8a9/ferret/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g8a9%2Fferret/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31580229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["benchmarking","interpretability","machine-learning","transformers"],"created_at":"2025-11-15T00:00:36.495Z","updated_at":"2026-04-09T00:35:20.691Z","avatar_url":"https://github.com/g8a9.png","language":"Python","funding_links":[],"categories":["Interpretability","Tools"],"sub_categories":["Interpretability/Explicability"],"readme":"![Ferret circular logo with the name to the right](/docs/source/_static/banner_v2.png)\n\n[![Latest PyPI version](https://img.shields.io/pypi/v/ferret-xai.svg)](https://pypi.python.org/pypi/ferret-xai)\n[![Documentation Status](https://readthedocs.org/projects/ferret/badge/?version=latest)](https://ferret.readthedocs.io/en/latest/?version=latest)\n[![HuggingFace Spaces Demo](https://img.shields.io/badge/HF%20Spaces-Demo-yellow)](https://huggingface.co/spaces/g8a9/ferret)\n[![YouTube Video](https://img.shields.io/badge/youtube-video-red)](https://www.youtube.com/watch?v=kX0HcSah_M4)\n[![arxiv preprint](https://img.shields.io/badge/arXiv-2208.01575-b31b1b.svg)](https://arxiv.org/abs/2208.01575)\n[![downloads badge](https://pepy.tech/badge/ferret-xai/month)](https://pepy.tech/project/ferret-xai)\n\nferret is Python library that streamlines the use and benchmarking of interpretability techniques on Transformers models.\n\n- Documentation: https://ferret.readthedocs.io\n- Paper: https://aclanthology.org/2023.eacl-demo.29/\n- Demo: https://huggingface.co/spaces/g8a9/ferret\n\n**ferret** is meant to integrate seamlessly with 🤗 **transformers** models, among which it currently supports text models only.\nWe provide:\n- 🔍 Four established interpretability techniques based on **Token-level Feature Attribution**. Use them to find the most relevant words to your model output quickly.\n- ⚖️ Six **Faithfulness and Plausibility evaluation protocols**. Benchmark any token-level explanation against these tests to guide your choice toward the most reliable explainer.  \n\nACL Anthology Bibkey:\n```bash\nattanasio-etal-2023-ferret\n```\n\n### 📝 Examples\n\nAll around tutorial (to test all explainers, evaluation metrics, and interface with XAI datasets): [Colab](https://colab.research.google.com/github/g8a9/ferret/blob/main/examples/benchmark.ipynb)\n\nText Classification\n\n- Intent Detection with Multilingual XLM RoBERTa: [Colab](https://colab.research.google.com/drive/17AXeA9-u7lOLlE_DWtUixMg7Mi0NFPIp?usp=sharing)\n\n\n## Getting Started\n\n### Installation\n\nFor the default installation, which does **not** include the dependencies for the speech XAI functionalities, \n\n```bash\npip install -U ferret-xai\n```\n\nOur main dependencies are 🤗 `tranformers` and `datasets`.\n\nIf the speech XAI functionalities are needed, then\n\n```\npip install -U ferret-xai[speech]\n```\n\nAt the moment, the speech XAI-related dependencies are the only extra ones, so installing with `ferret-xai[speech]` or `ferret-xai[all]` is equivalent.\n\n**Important** Some of our dependencies might use the package name for `scikit-learn` and that breaks ferret installation. \\\nIf your pip install command fails, try:\n\n```bash\nSKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True pip install -U ferret-xai\n```\n\nThis is hopefully a temporary situation!\n\n### Explain \u0026 Benchmark \n\nThe code below provides a minimal example to run all the feature-attribution explainers supported by ferret and benchmark them on faithfulness metrics.\n\nWe start from a common text classification pipeline\n\n```python\nfrom transformers import AutoModelForSequenceClassification, AutoTokenizer\nfrom ferret import Benchmark\n\nname = \"cardiffnlp/twitter-xlm-roberta-base-sentiment\"\nmodel = AutoModelForSequenceClassification.from_pretrained(name)\ntokenizer = AutoTokenizer.from_pretrained(name)\n```\n\nUsing *ferret* is as simple as: \n\n```python\nbench = Benchmark(model, tokenizer)\nexplanations = bench.explain(\"You look stunning!\", target=1)\nevaluations = bench.evaluate_explanations(explanations, target=1)\n\nbench.show_evaluation_table(evaluations)\n```\n\nBe sure to run the code in a Jupyter Notebook/Colab: the cell above will produce a nicely-formatted table to analyze the saliency maps.\n\n## Features\n\n**ferret** offers a *painless* integration with Hugging Face models and\nnaming conventions. If you are already using the\n[transformers](https://github.com/huggingface/transformers) library, you\nimmediately get access to our **Explanation and Evaluation API**.\n\n### Post-Hoc Explainers\n\n- Gradient (plain gradients or multiplied by input token embeddings) ([Simonyan et al., 2014](https://arxiv.org/abs/1312.6034))\n- Integrated Gradient (plain gradients or multiplied by input token embeddings) ([Sundararajan et al., 2017](http://proceedings.mlr.press/v70/sundararajan17a.html))\n- SHAP (via Partition SHAP approximation of Shapley values) ([Lundberg and Lee, 2017](https://proceedings.neurips.cc/paper/2017/hash/8a20a8621978632d76c43dfd28b67767-Abstract.html))\n- LIME ([Ribeiro et al., 2016](https://dl.acm.org/doi/abs/10.1145/2939672.2939778))\n\n### Evaluation Metrics\n\n**Faithfulness** measures:\n\n- AOPC Comprehensiveness ([DeYoung et al.,\n    2020](https://doi.org/10.18653/v1/2020.acl-main.408))\n- AOPC Sufficiency ([DeYoung et al.,\n    2020](https://doi.org/10.18653/v1/2020.acl-main.408))\n- Kendall's Tau correlation with Leave-One-Out token removal. ([Jain\n    and Wallace, 2019](https://aclanthology.org/N19-1357/))\n\n**Plausibility** measures:\n\n- Area-Under-Precision-Recall-Curve (soft score) ([DeYoung et al., 2020](https://doi.org/10.18653/v1/2020.acl-main.408))\n- Token F1 (hard score) ([DeYoung et al., 2020](https://doi.org/10.18653/v1/2020.acl-main.408))\n- Token Intersection Over Union (hard score) ([DeYoung et al., 2020](https://doi.org/10.18653/v1/2020.acl-main.408))\n\nSee our [paper](https://arxiv.org/abs/2208.01575) for details.\n\n## Visualization\n\nThe `Benchmark` class exposes easy-to-use table\nvisualization methods (e.g., within Jupyter Notebooks)\n\n```python\nbench = Benchmark(model, tokenizer)\n\n# Pretty-print feature attribution scores by all supported explainers\nexplanations = bench.explain(\"You look stunning!\")\nbench.show_table(explanations)\n\n# Pretty-print all the supported evaluation metrics\nevaluations = bench.evaluate_explanations(explanations)\nbench.show_evaluation_table(evaluations)\n```\n\n## Dataset Evaluations\n\nThe `Benchmark` class has a handy method to compute and\naverage our evaluation metrics across multiple samples from a dataset.\n\n```python\nimport numpy as np\nbench = Benchmark(model, tokenizer)\n\n# Compute and average evaluation scores one of the supported dataset\nsamples = np.arange(20)\nhatexdata = bench.load_dataset(\"hatexplain\")\nsample_evaluations =  bench.evaluate_samples(hatexdata, samples)\n\n# Pretty-print the results\nbench.show_samples_evaluation_table(sample_evaluations)\n```\n\n## Planned Developement\n\nSee [the changelog file](https://github.com/g8a9/ferret/blob/main/HISTORY.rst) for further\ndetails.\n\n- ✅ GPU acceleartion support for inference (**v0.4.0**)\n- ✅ Batched Inference for internal methods\\'s approximation steps (e.g., LIME or SHAP) (**v0.4.0**)\n- ⚙️ Simplified Task API to support NLI, Zero-Shot Text Classification, Language Modeling ([branch](https://github.com/g8a9/ferret/tree/task-API)).\n- ⚙️ Multi-sample explanation generation and evaluation\n- ⚙️ Support to explainers for seq2seq and autoregressive generation through [inseq](https://github.com/inseq-team/inseq).\n- ⚙️ New evaluation measure: Sensitivity, Stability ([Yin et al.](https://aclanthology.org/2022.acl-long.188/))\n- ⚙️ New evaluation measure: Area Under the Threshold-Performance Curve (AUC-TP) ([Atanasova et al.](https://aclanthology.org/2020.emnlp-main.263/))\n- ⚙️ New explainer: Sampling and Occlusion (SOC) ([Jin et al., 2020](https://arxiv.org/abs/1911.06194))\n- ⚙️ New explainer: Discretized Integrated Gradient (DIG) ([Sanyal and Ren, 2021](https://aclanthology.org/2021.emnlp-main.805/))\n- ⚙️ New explainer: Value Zeroing ([Mohebbi et al, 2023](https://aclanthology.org/2023.eacl-main.245/))\n- ⚙️ Support additional form of aggregation over embeddings' hidden dimension.\n\n\n## Authors\n\n- [Giuseppe Attanasio](https://gattanasio.cc)\n- [Eliana Pastor](mailto:eliana.pastor@centai.eu)\n- [Debora Nozza](https://deboranozza.com/)\n- Chiara Di Bonaventura\n\n## Credits\n\nThis package was created with Cookiecutter and the\n*audreyr/cookiecutter-pypackage* project template.\n\n- Cookiecutter: https://github.com/audreyr/cookiecutter\n- [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)\n\nLogo and graphical assets made by [Luca Attanasio](https://www.behance.net/attanasiol624d).\n\nIf you are using *ferret* for your work, please consider citing us!\n\n```bibtex\n@inproceedings{attanasio-etal-2023-ferret,\n    title = \"ferret: a Framework for Benchmarking Explainers on Transformers\",\n    author = \"Attanasio, Giuseppe and Pastor, Eliana and Di Bonaventura, Chiara and Nozza, Debora\",\n    booktitle = \"Proceedings of the 17th Conference of the European Chapter of the Association for Computational Linguistics: System Demonstrations\",\n    month = may,\n    year = \"2023\",\n    publisher = \"Association for Computational Linguistics\",\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg8a9%2Fferret","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fg8a9%2Fferret","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg8a9%2Fferret/lists"}