murano-interp 0.1.0a0__tar.gz

murano_interp-0.1.0a0/.coveragerc

@@ -0,0 +1,23 @@
+[run]
+source = examples,src
+omit =
+    */tests/*
+    */__pycache__/*
+    */venv/*
+    */build/*
+    */dist/*
+    setup.py
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise AssertionError
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+    @abstractmethod
+show_missing = True
+skip_covered = False
+precision = 2
+

murano_interp-0.1.0a0/.github/ISSUE_TEMPLATE/architecture_compatibility.yml

@@ -0,0 +1,121 @@
+name: 🧩 Architecture / Compatibility
+description: Murano works on one model or version but not another (cross-architecture, dependency-version, hardware)
+title: "[COMPAT] "
+labels:
+  - compatibility
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template when something works on one configuration but breaks on another:
+
+        - The same code works on Llama but fails on GPT-2 / Mistral / Qwen / OPT
+        - Worked on transformers 4.57 but breaks on 4.58
+        - Works on CPU but breaks on `device_map="auto"`
+        - Works locally but fails on a Slurm GPU node
+
+        For pure runtime errors (any model, any version), use the **Bug Report** template.
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight Checklist
+      options:
+        - label: I have a working configuration to compare against (i.e., I know it isn't a universal bug).
+          required: true
+        - label: I have searched [existing compatibility issues](https://github.com/UKPLab/murano/issues?q=is%3Aissue+label%3Acompatibility).
+          required: true
+
+  - type: dropdown
+    id: axis
+    attributes:
+      label: Compatibility axis
+      options:
+        - Model architecture (Llama vs GPT-2 vs Mistral vs ...)
+        - Model size / variant (Llama-1B vs Llama-8B)
+        - Library version (transformers / nnsight / nnterp / torch)
+        - Python version
+        - Device / GPU (CPU vs CUDA vs `device_map="auto"`)
+        - OS / platform
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: works_on
+    attributes:
+      label: Works on
+      description: The configuration where Murano runs correctly.
+      placeholder: e.g. meta-llama/Llama-3.2-1B-Instruct, transformers 4.57.6, nnterp 1.2.4
+    validations:
+      required: true
+
+  - type: input
+    id: breaks_on
+    attributes:
+      label: Breaks on
+      description: The configuration where Murano fails or returns wrong results.
+      placeholder: e.g. mistralai/Mistral-7B-Instruct-v0.3, transformers 4.58.0, nnterp 1.2.4
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: |
+        Code that runs cleanly on the "works on" config but fails on "breaks on".
+
+        **Please use small, public, no-auth models** for both halves of the comparison so we can
+        run them locally: e.g. `gpt2`, `meta-llama/Llama-3.2-1B-Instruct`,
+        `Qwen/Qwen2.5-0.5B`, `EleutherAI/pythia-70m`, `facebook/opt-125m`.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: error_output
+    attributes:
+      label: Error / wrong output
+      description: Exception trace, or the wrong-shape / wrong-value output you saw.
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: hardware
+    attributes:
+      label: Hardware
+      options:
+        - Single CUDA GPU
+        - Multi-GPU (`device_map="auto"`)
+        - CPU only
+        - Apple MPS
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: suspected_upstream
+    attributes:
+      label: Suspected upstream cause
+      description: Best guess at which dependency the underlying problem might live in. Pure speculation is fine.
+      options:
+        - nnsight
+        - nnterp
+        - transformers
+        - torch
+        - HuggingFace Hub / model weights
+        - Hardware / driver
+        - Murano itself
+        - Unknown
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Optional. Your hypothesis about the root cause, suspected breaking commit, etc.
+    validations:
+      required: false

murano_interp-0.1.0a0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,195 @@
+name: 🐛 Bug Report
+description: Report a crash, exception, or incorrect output in Murano
+title: "[BUG] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Filling in every section below saves us a round-trip.
+
+        Before submitting, please check:
+        - This issue hasn't already been reported by searching [existing issues](https://github.com/UKPLab/murano/issues?q=is%3Aissue+label%3Abug).
+        - You can reproduce the bug on a recent version of Murano.
+        - This is a bug in Murano itself, not a model-loading issue with a specific HuggingFace model
+          (those tend to be `transformers` or `nnsight` problems).
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight Checklist
+      options:
+        - label: I have searched [existing issues](https://github.com/UKPLab/murano/issues?q=is%3Aissue+label%3Abug) and this hasn't been reported yet.
+          required: true
+        - label: This is a single bug report (please file separate reports for different bugs).
+          required: true
+        - label: I can reproduce this with the latest released version of Murano.
+          required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      description: Which part of Murano is involved? Pick the closest match; the maintainer will refine.
+      options:
+        - Recording / activation extraction
+        - Interventions / generation modification
+        - Analysis / probing / lenses
+        - I/O / saving artifacts
+        - Pipeline / Step framework
+        - Plotting / visualization
+        - Cross-architecture / model loading
+        - Other / not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: what_wrong
+    attributes:
+      label: What's Wrong?
+      description: Describe what's happening that shouldn't be.
+      placeholder: |
+        When I call `model.record(texts, position="mean")` with a batch of 4, the returned tensor has shape (1, 2048) instead of (4, 2048).
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen instead?
+      placeholder: A `[N=4, d_model=2048]` tensor with one masked-mean activation per input.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: |
+        A self-contained, runnable code snippet that triggers the bug.
+
+        **Please use a small, public, no-auth model** so we can run your repro locally:
+        e.g. `meta-llama/Llama-3.2-1B-Instruct`, `gpt2`, `Qwen/Qwen2.5-0.5B`, `EleutherAI/pythia-70m`.
+        If the bug only occurs on a large or gated model, say so explicitly.
+      placeholder: |
+        ```python
+        from murano import MuranoModel
+        model = MuranoModel("gpt2")
+        acts = model.record(["hello", "world", "foo", "bar"], position="mean")
+        # expected acts.positive[0].shape == (4, 768); got (1, 768)
+        print(acts.positive[0].shape, acts.positive[0].dtype, acts.positive[0].device)
+        ```
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: error_output
+    attributes:
+      label: Error / wrong output
+      description: |
+        Full stack trace if it crashed. For numerical / shape bugs, paste the result of
+        `print(tensor.shape, tensor.dtype, tensor.device)` and any value comparison.
+      placeholder: |
+        Traceback (most recent call last):
+          File "...", line N, in ...
+            ...
+        ValueError: ...
+
+        # or, for wrong-output bugs:
+        actual:   torch.Size([1, 768]) bfloat16 cuda:0
+        expected: torch.Size([4, 768])
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: regression
+    attributes:
+      label: Is this a regression?
+      description: Did this work in a previous Murano version? If yes, please tell us which version still worked in the next field.
+      options:
+        - "Yes: it worked in a previous version"
+        - "No: this never worked / new install"
+        - "Don't know"
+    validations:
+      required: true
+
+  - type: input
+    id: last_working_version
+    attributes:
+      label: Last working Murano version (if regression)
+      description: e.g. `0.1.0`. Skip if this isn't a regression.
+      placeholder: e.g. 0.1.0
+    validations:
+      required: false
+
+  - type: dropdown
+    id: reproducibility
+    attributes:
+      label: Reproducibility
+      options:
+        - Always
+        - Sometimes (intermittent)
+        - Only happened once
+        - Haven't tried to reproduce
+    validations:
+      required: true
+
+  - type: dropdown
+    id: architecture
+    attributes:
+      label: Model architecture
+      description: nnterp standardizes module names across these. Pick the family of the model in your repro.
+      options:
+        - Llama
+        - GPT-2
+        - Mistral
+        - Qwen
+        - OPT
+        - Other
+        - Not applicable
+    validations:
+      required: true
+
+  - type: dropdown
+    id: hardware
+    attributes:
+      label: Hardware
+      options:
+        - Single CUDA GPU
+        - Multi-GPU (`device_map="auto"`)
+        - CPU only
+        - Apple MPS
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Library versions
+      description: |
+        Paste the output of:
+        ```
+        python -c "import murano, nnsight, nnterp, transformers, torch; print('murano', murano.__version__); print('nnsight', nnsight.__version__); print('nnterp', nnterp.__version__); print('transformers', transformers.__version__); print('torch', torch.__version__)"
+        ```
+      placeholder: |
+        murano 0.1.0
+        nnsight 0.5.1
+        nnterp 1.2.4
+        transformers 4.58.0
+        torch 2.8.0+cu126
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Workarounds you've tried, related issues, model-specific notes.
+    validations:
+      required: false

murano_interp-0.1.0a0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Discussions
+    url: https://github.com/UKPLab/murano/discussions
+    about: Ask questions, share usage tips, and chat with other Murano users.
+  - name: 📖 Documentation
+    url: https://ukplab.github.io/murano/
+    about: Read the guides, API reference, and reproduction gallery.
+  - name: 🚀 Quickstart
+    url: https://ukplab.github.io/murano/docs/getting-started/quickstart/
+    about: New to Murano? Start here.
+  - name: 🧪 Reproduction Gallery
+    url: https://ukplab.github.io/murano/reproductions/
+    about: Browse Murano-powered reproductions of published interpretability work.

murano_interp-0.1.0a0/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,70 @@
+name: 📖 Documentation
+description: Report unclear, wrong, or missing documentation
+title: "[DOCS] "
+labels:
+  - documentation
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping us improve the docs! This template is for issues with the documentation
+        itself: guides, API reference, README, examples, or comments in the source.
+
+        For runtime bugs in the code, please use the **Bug Report** template instead.
+
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind of issue
+      options:
+        - Wrong (the docs say something incorrect)
+        - Unclear (the docs are ambiguous or hard to follow)
+        - Missing (a topic isn't documented at all)
+        - Missing code examples
+        - Out of date (an example uses an old API)
+        - Broken link
+        - Typo / formatting
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Where is the issue?
+      description: URL, file path, or section heading. Multiple locations OK.
+      placeholder: e.g. https://ukplab.github.io/murano/docs/guides/record/ or src/murano/steps/record.py:230
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong / what's missing?
+      description: Quote the current text or describe what you couldn't find.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested improvement
+      description: A concrete change in mind. If you can word it, please do; that's the fastest path to a merged fix.
+      placeholder: |
+        Replace:
+          "Pass `position="last"` to record only the final token."
+        with:
+          "Pass `position="last"` to record only the final non-padding token of each sequence (the position is determined per-row from the attention mask)."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: impact
+    attributes:
+      label: Impact
+      description: How badly does this confuse new users?
+      options:
+        - "High: blocks users from using a feature"
+        - "Medium: feature is usable but takes guesswork"
+        - "Low: minor confusion or polish"
+    validations:
+      required: true

murano_interp-0.1.0a0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,114 @@
+name: ✨ Feature Request
+description: Suggest a new step, metric, lens, or capability for Murano
+title: "[FEATURE] "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe the use case so we can scope it well.
+
+        Before submitting, please check if this has been requested already in [open enhancements](https://github.com/UKPLab/murano/issues?q=is%3Aissue+label%3Aenhancement).
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight Checklist
+      options:
+        - label: I have searched [existing requests](https://github.com/UKPLab/murano/issues?q=is%3Aissue+label%3Aenhancement) and this hasn't been requested yet.
+          required: true
+        - label: This is a single feature request (file separate issues for unrelated ideas).
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: What are you trying to do that you can't do well today? Concrete use case > abstract framing.
+      placeholder: |
+        I'm doing causal tracing experiments and want to intervene at one layer while recording the
+        downstream effect at another, in a single forward pass. Currently `Record` and `Intervene` are
+        separate steps, which means two forward passes per prompt.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What API or step would you add? Show an example call site if you can.
+      placeholder: |
+        A `RecordIntervene` step that takes `intervene_layer`, `intervene_fn`, `record_layer`, and runs
+        a single nnsight trace.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you've thought about and why they don't fit.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Where would this live?
+      description: Best guess at where the change would land in the codebase.
+      options:
+        - New `Step` (`src/murano/steps/...`)
+        - New artifact / dataclass
+        - New plotting helper (`src/murano/plotting/...`)
+        - New `MuranoModel` method
+        - New CLI / IO helper
+        - I'm not sure; you decide
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority for you
+      description: How important is this to your own work? We treat this as a signal, not a commitment.
+      options:
+        - "Critical: blocking my paper / project"
+        - "High: significant impact on productivity"
+        - "Medium: would be very helpful"
+        - Nice to have
+    validations:
+      required: true
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Concrete use case
+      description: Walk us through one realistic scenario where you'd use this. Useful for grepping prior issues with similar intent.
+      placeholder: |
+        I'm running activation patching across 24 layers for a 1B model on 200 prompts.
+        With separate Record + Intervene steps, I do 200 × 2 = 400 forward passes.
+        With this feature, I'd do 200 and the wall-clock drops from ~10 min to ~5 min.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: pr_status
+    attributes:
+      label: Have you started a PR?
+      description: Tells us whether to expect "review my code" or "design and build it for me".
+      options:
+        - "No: want to discuss first"
+        - "Considering / sketching"
+        - "Yes: draft PR is open (link below)"
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: References / draft PR link
+      description: Links to papers, prior implementations, related discussions, or your draft PR.
+    validations:
+      required: false

murano_interp-0.1.0a0/.github/ISSUE_TEMPLATE/reproduction_submission.yml

@@ -0,0 +1,81 @@
+name: 📓 Reproduction Submission
+description: Submit a Murano-powered reproduction of an interpretability paper for the gallery
+title: "[REPRODUCTION] "
+labels:
+  - reproduction
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for sharing your reproduction! Submissions land here for review before being added
+        to the [Reproduction Gallery](https://ukplab.github.io/murano/reproductions/).
+
+        We expect each submission to include a runnable notebook and the original paper reference.
+        See the [submit guide](https://ukplab.github.io/murano/docs/reproductions/submit/) for the
+        format reviewers will check against.
+
+  - type: input
+    id: submitter
+    attributes:
+      label: Your name
+      description: How you'd like to be credited in the gallery.
+      placeholder: e.g. Federico Tiblias
+    validations:
+      required: true
+
+  - type: input
+    id: paper
+    attributes:
+      label: Paper title or DOI
+      placeholder: e.g. Representation Engineering (Zou et al., 2023); arXiv:2310.01405
+    validations:
+      required: true
+
+  - type: input
+    id: notebook
+    attributes:
+      label: Notebook URL
+      description: Public link to a runnable `.ipynb` (GitHub, gist, Colab, nbviewer).
+      placeholder: https://github.com/your-org/your-repo/blob/main/notebook.ipynb
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Short description
+      description: What does the notebook reproduce, and what should reviewers focus on?
+      placeholder: Reproduces the linear-probe analysis from Section 4. Uses Llama-3.2-1B and 1k contrastive prompts.
+    validations:
+      required: true
+
+  - type: input
+    id: code_repo
+    attributes:
+      label: Original code repo (optional)
+      description: Link to the paper's reference implementation, if any.
+      placeholder: https://github.com/...
+    validations:
+      required: false
+
+  - type: dropdown
+    id: hardware_required
+    attributes:
+      label: Hardware required to re-run
+      description: Sets reviewer expectations on whether they can verify the notebook locally.
+      options:
+        - CPU OK (small/no model, or precomputed activations)
+        - Single consumer GPU (≤16 GB)
+        - Single A100 / H100 (40–80 GB)
+        - Multi-GPU
+        - Other / specify in description
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Optional. Known caveats, deviations from the paper, planned follow-ups.
+    validations:
+      required: false

murano_interp-0.1.0a0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+### Summary :memo:
+_Write an overview about it._
+
+### Details
+_Describe more what you did on changes._
+1. (...)
+2. (...)
+
+### Bugfixes :bug: (delete if dind't have any)
+-
+
+### Checks
+- [ ] Closed #798
+- [ ] Tested Changes
+- [ ] Stakeholder Approval

murano_interp-0.1.0a0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"