Documentation

What is GRADIEND?

GRADIEND is a method for learning features within neural networks by training an encoder-decoder architecture on model gradients. With this library you can find where a language model encodes a feature (e.g. gender, race, religion) and rewrite the model to strengthen or weaken it—for example debias it—while keeping other behaviour.

GRADIEND works by: 1. Training an encoder-decoder network on gradients computed from masked text predictions 2. Learning a single latent feature neuron that encodes the desired interpretation (e.g., gender bias) 3. Using the decoder to modify the base model's weights, enabling targeted feature manipulation

The method is described in detail in the paper: GRADIEND: Feature Learning within Neural Networks Exemplified through Biases (ICLR 2026, Drechsel & Herbold, 2025).

While GRADIEND is methodologically defined to work with any gradient-learned and weight-based model, this library currently documents and supports text prediction as the primary workflow. Preliminary TextClassification code exists, but it is experimental in this release and not recommended as the starting point for new users.

Example use cases (gradiend/examples on GitHub): - English pronouns — notebook; script - German gender–case - Sentiment - Multi-seed stability

Links: GitHub · PyPI · arXiv (main paper) · arXiv (German articles)

---

Get started

• Installation — Install the package and optional dependencies.
• Train your first GRADIEND model — A minimal runnable example to train and evaluate in a few steps.
• Read the Python package paper: The GRADIEND Python Package: An End-to-End System for Gradient-Based Feature Learning — describes the design and implementation of the library.

---

Tutorials

Step-by-step workflows, following the 5 steps of above's overview:

1. Workflow Overview — Tutorial Overview.
2. Feature Selection and Data Generation — Build training and neutral data from raw text (syncretism, spaCy, one filter per grammatical cell). Part 1 of the detailed workflow.
3. GRADIEND Training — Experiment layout, pruning (pre/post), multi-seed, convergence plot, and training options in detail.
4. Intra-Model Evaluation — Encoder analysis (are target classes seperated?) and decoder evaluation (determine parameters to update model's feature behavior under a language modeling constraint).
5. Model Rewrite — Using decoder-selected settings to rewrite base-model weights in memory or on disk.
6. Inter-Model Evaluation — Comparing multiple runs: top-k overlap and heatmap.

---

Guides

When you need to understand a topic or look up options:

• Core classes and use cases — Overview of the most important classes and when to use them.
• Data handling — Data formats, columns, and balancing (DataFrames, per-class dicts, Hugging Face datasets).
• Pruning — Pre-pruning (from gradients) and post-pruning (from weights); when and how to use them.
• Evaluation & visualization — Encoder and decoder evaluation, convergence and top-k plots, and how to customize plots.
• Saving & loading — Where results are stored and how to reload a trained model.
• Training arguments — Full parameter reference, including multi-seed training and seed report format.
• Token prediction methods — Differences between masked-token, decoder-only, and seq2seq objectives.
• Data splits — Row-level vs vocabulary-held-out splitting.
• Cross-model comparison — Compare runs, features, and convergent seeds.
• Oriented cross-encoding matrix — Compute and interpret feature-class cross-encoding matrices.
• Multi-seed analysis — Evaluate and plot across convergent seed checkpoints.
• Trainer suites — Orchestrate many related feature-pair runs (TrainerSuite, TrainerCollection).
• Decoder evaluation targets — Row-wise vs class-based decoder scoring.
• Decoder-only models — Use causal (decoder-only) LMs with the same API; optional MLM head for better mask gradients.

---

Reference

• Examples — All example scripts with short descriptions.
• API reference — Auto-generated from docstrings; main classes and entry points.
• FAQ — Troubleshooting and common pitfalls.
• Citation — How to cite the paper and library.