fix(deps): address review findings on transformers v5 migration

- Bump sentence-transformers lower bound 5.2.0 → 5.4.0. The new ranker /
  embedder paths (cross_encoder[0] subscript, sentence_transformers.
  sentence_transformer subpackage, get_embedding_dimension) all landed
  in 5.4.0; the previous floor would have ModuleNotFoundError'd /
  AttributeError'd anyone resolving 5.2.x–5.3.x.
- Constrain EmbedderFineTuningConfig.warmup_ratio to (0, 1). v5
  TrainingArguments interprets warmup_steps>=1 as a raw step count
  and <1 as a fraction, so a stray warmup_ratio=1.0 would silently
  produce one warmup step instead of full-training warmup.
- Refresh tests/test_deps.py synthetic metadata fixtures to v5
  version strings so the resolver tests exercise the version range
  we ship, not the v4 range we just left behind.
- Trim the v4→v5 narrating comments down to the WHY of the current
  code; per-line migration history belongs in the commit log.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: voorhs

pyproject.toml

@@ -52,7 +52,7 @@ dependencies = [
 catboost = ["catboost (>=1.2.8,<2.0.0)"]
 peft = ["peft (>= 0.10.0, !=0.15.0, !=0.15.1, <1.0.0)"]
 transformers = ["transformers[torch] (>=5.0.0,<6.0.0)"]
-sentence-transformers = ["sentence-transformers (>=5.2.0,<6.0.0)"]
+sentence-transformers = ["sentence-transformers (>=5.4.0,<6.0.0)"]
 dspy = [
     "dspy (>=2.6.5,<3.0.0)",
 ]

src/autointent/_wrappers/embedder/sentence_transformers.py

@@ -323,8 +323,7 @@ def train(self, utterances: list[str], labels: ListOfLabels, config: EmbedderFin
                 per_device_train_batch_size=config.batch_size,
                 per_device_eval_batch_size=config.batch_size,
                 learning_rate=config.learning_rate,
-                # transformers v5 deprecated `warmup_ratio` in favor of `warmup_steps`,
-                # which now accepts a float < 1.0 as a fraction of total training steps.
+                # warmup_steps accepts a float < 1 as a fraction of total steps.
                 warmup_steps=config.warmup_ratio,
                 fp16=config.fp16,
                 bf16=config.bf16,

src/autointent/_wrappers/ranker.py

@@ -136,10 +136,8 @@ def __init__(
         if classifier_head is not None or self.config.train_head:
             self._train_head = True
             self._activations_list: list[npt.NDArray[Any]] = []
-            # sentence-transformers v5 restructured CrossEncoder into a nn.Sequential
-            # of modules: cross_encoder[0] is a Transformer wrapping the underlying
-            # AutoModelForSequenceClassification (exposed as .auto_model). The
-            # classifier head still lives on that HF model.
+            # CrossEncoder is a nn.Sequential of modules; [0] is the Transformer
+            # wrapping the HF model exposed as .auto_model.
             self._hook_handler = self.cross_encoder[0].auto_model.classifier.register_forward_hook(
                 self._classifier_hook
             )
@@ -317,9 +315,6 @@ def load(cls, path: Path, override_config: CrossEncoderConfig | None = None) ->
 
     def clear_ram(self) -> None:
         """Clear model from RAM and GPU memory."""
-        # sentence-transformers v5 CrossEncoder is itself a nn.Sequential, so we
-        # call .cpu() on the wrapper directly instead of the (now-absent)
-        # underlying `.model` attribute.
         self.cross_encoder.cpu()
         del self.cross_encoder
         gc.collect()

src/autointent/configs/_transformers.py

@@ -28,7 +28,10 @@ class EmbedderFineTuningConfig(BaseModel):
     batch_size: int
     margin: float = Field(default=0.5)
     learning_rate: float = Field(default=2e-5)
-    warmup_ratio: float = Field(default=0.1)
+    # Fed to TrainingArguments.warmup_steps in v5, which interprets float<1 as
+    # a fraction of total steps and float>=1 as a raw step count. Restrict to
+    # (0, 1) so warmup_ratio=1.0 doesn't silently become a single step.
+    warmup_ratio: float = Field(default=0.1, gt=0, lt=1)
     early_stopping_patience: int = Field(default=1)
     early_stopping_threshold: float = Field(default=0.0)
     val_fraction: float = Field(default=0.2)

tests/test_deps.py

@@ -104,7 +104,7 @@ def test_resolve_recurses_into_nested_extra(monkeypatch: pytest.MonkeyPatch) ->
     _patch_metadata(
         monkeypatch,
         {
-            "autointent": ["transformers[torch]>=4.49.0,<5.0.0 ; extra == 'transformers'"],
+            "autointent": ["transformers[torch]>=5.0.0,<6.0.0 ; extra == 'transformers'"],
             "transformers": [
                 "torch>=2.2 ; extra == 'torch'",
                 "accelerate>=0.26.0 ; extra == 'torch'",
@@ -180,13 +180,13 @@ def test_require_detects_missing_nested_accelerate(monkeypatch: pytest.MonkeyPat
     _patch_metadata(
         monkeypatch,
         {
-            "autointent": ["transformers[torch]>=4.49.0,<5.0.0 ; extra == 'transformers'"],
+            "autointent": ["transformers[torch]>=5.0.0,<6.0.0 ; extra == 'transformers'"],
             "transformers": [
                 "torch>=2.2 ; extra == 'torch'",
                 "accelerate>=0.26.0 ; extra == 'torch'",
             ],
         },
-        {"transformers": "4.49.0", "torch": "2.2.0"},  # accelerate absent
+        {"transformers": "5.0.0", "torch": "2.2.0"},  # accelerate absent
     )
     with pytest.raises(ImportError) as exc:
         deps.require("transformers")
@@ -200,7 +200,7 @@ def test_require_reports_extra_package_entirely_missing(monkeypatch: pytest.Monk
     # `transformers[torch]` requirement is flagged as missing with the install hint.
     _patch_metadata(
         monkeypatch,
-        {"autointent": ["transformers[torch]>=4.49.0,<5.0.0 ; extra == 'transformers'"]},
+        {"autointent": ["transformers[torch]>=5.0.0,<6.0.0 ; extra == 'transformers'"]},
         {},  # transformers (and everything else) absent
     )
     with pytest.raises(ImportError) as exc: