candle-mi 0.1.12

Mechanistic interpretability for language models in Rust, built on candle
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT OR Apache-2.0
"""Fetch Maar et al. (2026) supplementary `.zip` from OpenReview.

Maar's paper text documents the contrastive activation steering protocol
only for `Gemma 2 9B` (layer 27, newline token, m=1.5).  Per-model layer
and token-position specs for the other 22 models in their wide sweep
(including `Gemma 2 2B`, `Llama 3.2 1B`, `Llama 3.2 3B`) live in the
supplementary materials attached to the OpenReview submission
`Z10pxu0Q7X`.

This script attempts to download that supplementary `.zip` via the
OpenReview API.  If the API returns an HTML page (login required) or a
403, the script prints a manual-download URL the user can open in a
browser.

## Usage

```bash
python scripts/maar_supplementary_fetch.py \
    --output examples/results/maar_contrastive_steering/maar_supplementary.zip
```

After download, point `examples/maar_contrastive_steering` at the
extracted protocol via `--maar-supplementary <path-to-extracted-dir>`,
or convert the prompts to our JSON schema via the (post-v0.1.12) helper
`scripts/maar_to_candle_mi_prompts.py`.

## Status as of v0.1.12

The OpenReview attachment endpoint requires a logged-in session in most
configurations.  If `--api-token` is not provided, this script will
likely report `403 Forbidden` and print the manual URL.  Manual download
remains the fall-back, recorded in the prompts JSON `source` field.
"""

import argparse
import sys
from pathlib import Path

OPENREVIEW_PAPER_ID = "Z10pxu0Q7X"
OPENREVIEW_FORUM_URL = f"https://openreview.net/forum?id={OPENREVIEW_PAPER_ID}"
OPENREVIEW_ATTACHMENT_URL = (
    f"https://openreview.net/attachment?"
    f"id={OPENREVIEW_PAPER_ID}&name=supplementary_material"
)
OPENREVIEW_API_ATTACHMENT_URL = (
    f"https://api2.openreview.net/attachment?"
    f"id={OPENREVIEW_PAPER_ID}&name=supplementary_material"
)


def fetch(output_path: Path, api_token: str | None) -> int:
    """Attempt to fetch the supplementary .zip.  Returns 0 on success,
    non-zero on failure."""
    try:
        import requests
    except ImportError:
        sys.stderr.write(
            "ERROR: `requests` package is required.  "
            "Install with `python -m pip install requests`.\n"
        )
        return 2

    headers = {}
    if api_token:
        headers["Authorization"] = f"Bearer {api_token}"

    print(f"Attempting download from {OPENREVIEW_API_ATTACHMENT_URL} ...")
    try:
        resp = requests.get(
            OPENREVIEW_API_ATTACHMENT_URL,
            headers=headers,
            timeout=120,
            stream=True,
        )
    except requests.RequestException as exc:
        sys.stderr.write(f"ERROR: request failed: {exc}\n")
        print_manual_fallback()
        return 3

    if resp.status_code != 200:
        sys.stderr.write(
            f"ERROR: HTTP {resp.status_code} from OpenReview API; "
            f"likely requires authentication.\n"
        )
        print_manual_fallback()
        return 4

    content_type = resp.headers.get("Content-Type", "")
    if "zip" not in content_type and "octet-stream" not in content_type:
        sys.stderr.write(
            f"ERROR: unexpected Content-Type '{content_type}'; "
            f"expected a binary zip.  Likely an HTML login redirect.\n"
        )
        print_manual_fallback()
        return 5

    output_path.parent.mkdir(parents=True, exist_ok=True)
    total = 0
    with output_path.open("wb") as f:
        for chunk in resp.iter_content(chunk_size=65_536):
            if chunk:
                f.write(chunk)
                total += len(chunk)
    print(f"Downloaded {total / 1024 / 1024:.2f} MiB to {output_path}")
    return 0


def print_manual_fallback() -> None:
    print(
        "\n=== Manual download fall-back ===\n"
        f"1. Open in a browser:  {OPENREVIEW_FORUM_URL}\n"
        '2. Sign in to OpenReview (free account).\n'
        '3. Scroll to "Supplementary Material" attachment.\n'
        f"4. Save the .zip to your target output path.\n"
        "\n"
        "After download, point the example at the extracted protocol\n"
        "or convert the prompts to our JSON schema (post-v0.1.12).\n",
        file=sys.stderr,
    )


def main() -> int:
    sys.stdout.reconfigure(encoding="utf-8")
    parser = argparse.ArgumentParser(
        description="Fetch Maar et al. (2026) supplementary .zip from OpenReview."
    )
    parser.add_argument(
        "--output",
        type=Path,
        default=Path("examples/results/maar_contrastive_steering/maar_supplementary.zip"),
        help="Where to save the downloaded .zip.",
    )
    parser.add_argument(
        "--api-token",
        default=None,
        help="OpenReview API token (optional; tries unauthenticated first).",
    )
    args = parser.parse_args()
    return fetch(args.output, args.api_token)


if __name__ == "__main__":
    sys.exit(main())