logo

tdhook 🤖🪝

Documentation tdhook license uv Ruff python versions arXiv

codecov ci publish docs

Interpretability with tensordict and torch hooks.

Getting Started

Most methods should work with minimal configuration. Here's a basic example of running Integrated Gradients on a VGG16 model (full example available here):

from tdhook.attribution import IntegratedGradients

# Define attribution target (e.g., zebra class = 340)
def init_attr_targets(targets, _):
    zebra_logit = targets["output"][..., 340]
    return TensorDict(out=zebra_logit, batch_size=targets.batch_size)

# Compute attribution
with IntegratedGradients(init_attr_targets=init_attr_targets).prepare(model) as hooked_model:
    td = TensorDict({
        "input": image_tensor,
        ("baseline", "input"): torch.zeros_like(image_tensor) # required for integrated gradients
    }).unsqueeze(0)
    td = hooked_model(td) # Access attribution with td.get(("attr", "input"))

Composition

TDHook's composability goal is that every public method can participate in a declared workflow, with compatible hooks combined into the fewest safe model executions. The contract distinguishes a composed model (multiple inputs, outputs, or submodules), same-run hook composition, and workflow steps exchanging named TensorDict values. See the composition contract for the execution rules, conformance evidence, and current implementation status.

To dig deeper, see the documentation.

Skills

An agent skill is available for tdhook. It provides AI guidance for attribution, activation analysis, probing, steering, and weight-level interventions—including when to use each method and how to wire TensorDict keys.

Features

Config

This project uses uv to manage python dependencies and run scripts, as well as just to run commands.

Citation

If you're using tdhook in your research, please cite it using the following BibTeX entry:

@misc{poupart2025tdhooklightweightframeworkinterpretability,
      title={TDHook: A Lightweight Framework for Interpretability},
      author={Yoann Poupart},
      year={2025},
      eprint={2509.25475},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2509.25475},
}

License

tdhook is licensed under the MIT License. See LICENSE for details.

Project links

Data verified by PyPI on Aug 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Xmaster6y from gravatar.com Xmaster6y

Credits

Author: Yoann Poupart

GitHub Statistics

Data verified by PyPI on Aug 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tdhook-0.2.0.tar.gz (86.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

tdhook-0.2.0-py3-none-any.whl (83.7 kB view details)

Uploaded Python 3

File details

Details for the file tdhook-0.2.0.tar.gz.

File metadata

  • Download URL: tdhook-0.2.0.tar.gz
  • Upload date:
  • Size: 86.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tdhook-0.2.0.tar.gz
Algorithm Hash digest
SHA256 e01bf8994d0506951f70f0b064b10b90484bae27211fa8a847ed05944b54beae
MD5 7829dea507c6009b5de26a715ebbc78e
BLAKE2b-256 cbc82ac21e42bb02ffed5c3b951fe1d42874950b9bc6519d9e0db15748b96500

See more details on using hashes here.

Provenance

The following attestation bundles were made for tdhook-0.2.0.tar.gz:

Publisher: publish.yml on Xmaster6y/tdhook

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tdhook-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: tdhook-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 83.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tdhook-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 cb9f9ac6cf1f50ef6c5875f0d1c8b6384b17547e355ba95853b344e030f1c7eb
MD5 f667f17276afc2b23be5da68215419f1
BLAKE2b-256 b736809528e1e867177b819a15ff3f52129bf8bd76d985b87c120df9224cc2e9

See more details on using hashes here.

Provenance

The following attestation bundles were made for tdhook-0.2.0-py3-none-any.whl:

Publisher: publish.yml on Xmaster6y/tdhook

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page