deprecate remaining hooked entry points

demos/Othello_GPT.ipynb

@@ -279,7 +279,18 @@
    "cell_type": "code",
    "execution_count": 56,
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "DeprecationWarning:\n",
+      "\n",
+      "HookedTransformer is deprecated and will be removed in 4.0. Use TransformerBridge.boot_transformers(...) instead, then call enable_compatibility_mode() for HookedTransformer-equivalent numerics.\n",
+      "\n"
+     ]
+    }
+   ],
    "source": [
     "import transformer_lens.utilities as utils\n",
     "\n",

demos/doc_sanitize.cfg

@@ -33,3 +33,7 @@ replace: \1
 [regex6d]
 regex: (0\.[1-9]\d{2})\d+
 replace: \1
+
+[regex7]
+regex: [^\n]*DeprecationWarning:(?=\n\nHookedTransformer is deprecated and will be removed in 4\.0\. Use TransformerBridge\.boot_transformers\(\.\.\.\) instead, then call enable_compatibility_mode\(\) for HookedTransformer-equivalent numerics\.)
+replace: DeprecationWarning:

tests/unit/test_deprecation_warnings.py

@@ -0,0 +1,64 @@
+"""Regression coverage for deprecated legacy entry points."""
+
+from __future__ import annotations
+
+import warnings
+
+import pytest
+
+
+def _small_config():
+    from transformer_lens import HookedTransformerConfig
+
+    return HookedTransformerConfig(
+        n_layers=1,
+        d_model=16,
+        d_head=4,
+        n_heads=4,
+        n_ctx=8,
+        d_vocab=20,
+        attn_only=True,
+    )
+
+
+def _assert_single_deprecation(constructor, class_name: str) -> None:
+    with pytest.warns(DeprecationWarning, match=class_name) as caught:
+        constructor()
+
+    assert len(caught) == 1
+    assert "TransformerBridge.boot_transformers" in str(caught[0].message)
+    assert "4.0" in str(caught[0].message)
+
+
+def test_importing_transformer_lens_emits_no_deprecation_warning():
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        import transformer_lens  # noqa: F401
+
+    assert not [warning for warning in caught if issubclass(warning.category, DeprecationWarning)]
+
+
+def test_hooked_transformer_constructor_warns_once():
+    from transformer_lens import HookedTransformer
+
+    _assert_single_deprecation(lambda: HookedTransformer(_small_config()), "HookedTransformer")
+
+
+def test_hooked_encoder_constructor_warns_once():
+    from transformer_lens import HookedEncoder
+
+    _assert_single_deprecation(lambda: HookedEncoder(_small_config()), "HookedEncoder")
+
+
+def test_bert_next_sentence_prediction_constructor_warns_once():
+    from transformer_lens import BertNextSentencePrediction
+
+    _assert_single_deprecation(
+        lambda: BertNextSentencePrediction(object()), "BertNextSentencePrediction"
+    )
+
+
+def test_direct_hooked_root_module_construction_warns_once():
+    from transformer_lens import HookedRootModule
+
+    _assert_single_deprecation(HookedRootModule, "HookedRootModule")

transformer_lens/BertNextSentencePrediction.py

@@ -5,6 +5,7 @@
 to e.g. GPT style transformers.
 """
 
+import warnings
 from typing import Any, Dict, List, Optional, Tuple, Union, overload
 
 import torch
@@ -31,6 +32,13 @@ class BertNextSentencePrediction:
     """
 
     def __init__(self, model: Any):
+        warnings.warn(
+            "BertNextSentencePrediction is deprecated and will be removed in 4.0. Use "
+            "TransformerBridge.boot_transformers(...) for BERT-style models; see "
+            "demos/BERT.ipynb.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.model = model
 
     def __call__(

transformer_lens/HookedEncoder.py

@@ -8,6 +8,7 @@
 
 import logging
 import os
+import warnings
 from typing import Any, Dict, List, Optional, Tuple, TypeVar, Union, cast, overload
 
 import torch
@@ -58,6 +59,12 @@ def __init__(
         **kwargs: Any,
     ):
         super().__init__()
+        warnings.warn(
+            "HookedEncoder is deprecated and will be removed in 4.0. Use "
+            "TransformerBridge.boot_transformers(...) instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if isinstance(cfg, Dict):
             cfg = HookedTransformerConfig(**cfg)
         elif isinstance(cfg, str):

transformer_lens/HookedRootModule.py

@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 import logging
+import warnings
 from collections.abc import Callable, Iterable
 from contextlib import contextmanager
 from functools import partial
@@ -54,6 +55,13 @@ class HookedRootModule(HookIntrospectionMixin, nn.Module):
 
     def __init__(self, *args: Any):
         super().__init__()
+        if type(self) is HookedRootModule:
+            warnings.warn(
+                "HookedRootModule is deprecated and will be removed in 4.0. Use "
+                "TransformerBridge.boot_transformers(...) instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self.is_caching = False
         self.context_level = 0
 

transformer_lens/HookedTransformer.py

@@ -13,6 +13,7 @@
 
 import logging
 import os
+import warnings
 from collections.abc import Generator
 from typing import (
     Any,
@@ -164,6 +165,13 @@ def __init__(
             default_padding_side: Which side to pad on.
         """
         super().__init__()
+        warnings.warn(
+            "HookedTransformer is deprecated and will be removed in 4.0. Use "
+            "TransformerBridge.boot_transformers(...) instead, then call "
+            "enable_compatibility_mode() for HookedTransformer-equivalent numerics.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if isinstance(cfg, str):
             raise ValueError(
                 "Please pass in a config dictionary or HookedTransformerConfig object. If you want to load a "