Breaking change from `sentence_transformers` 4.1.0 to 5.1.1 in citatio

[nilswiersma]

I've set up citatio with pip (pip install -e .), grabbing the latest versions of some of the packages from the pyproject.toml. When sending a search command to the server, there seems to be a breaking change between versions of sentence_transformers. I've included some version information below.

Setting up citatio with pdm (which sticks to pdm.lock) works without problems.

(.venv) $ python --version
Python 3.13.3

(.venv) $ cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=25.04
DISTRIB_CODENAME=plucky
DISTRIB_DESCRIPTION="Ubuntu 25.04"

(.venv) $ pip freeze
accelerate==1.10.1
aiohappyeyeballs==2.6.1
aiohttp==3.13.0
aiosignal==1.4.0
annotated-types==0.7.0
anyio==4.11.0
asmtransformers @ file:///home/nils/repos/asmtransformers/citatio/../asmtransformers
attrs==25.4.0
certifi==2025.10.5
charset-normalizer==3.4.3
-e git+https://github.com/NetherlandsForensicInstitute/asmtransformers.git@9a51f15c1b4103b17687456dba9a23c21d451564#egg=citatio&subdirectory=citatio
click==8.3.0
contourpy==1.3.3
cycler==0.12.1
datasets==4.1.1
dill==0.4.0
dnspython==2.8.0
email-validator==2.3.0
fastapi==0.118.0
fastapi-cli==0.0.13
fastapi-cloud-cli==0.3.0
filelock==3.19.1
fonttools==4.60.1
frozenlist==1.8.0
fsspec==2025.9.0
h11==0.16.0
hf-xet==1.1.10
httpcore==1.0.9
httptools==0.6.4
httpx==0.28.1
huggingface-hub==0.35.3
idna==3.10
itsdangerous==2.2.0
Jinja2==3.1.6
joblib==1.5.2
kiwisolver==1.4.9
markdown-it-py==4.0.0
MarkupSafe==3.0.3
matplotlib==3.10.6
mdurl==0.1.2
mpmath==1.3.0
multidict==6.7.0
multiprocess==0.70.16
networkx==3.5
numpy==2.3.3
nvidia-cublas-cu12==12.8.4.1
nvidia-cuda-cupti-cu12==12.8.90
nvidia-cuda-nvrtc-cu12==12.8.93
nvidia-cuda-runtime-cu12==12.8.90
nvidia-cudnn-cu12==9.10.2.21
nvidia-cufft-cu12==11.3.3.83
nvidia-cufile-cu12==1.13.1.3
nvidia-curand-cu12==10.3.9.90
nvidia-cusolver-cu12==11.7.3.90
nvidia-cusparse-cu12==12.5.8.93
nvidia-cusparselt-cu12==0.7.1
nvidia-nccl-cu12==2.27.3
nvidia-nvjitlink-cu12==12.8.93
nvidia-nvtx-cu12==12.8.90
orjson==3.11.3
packaging==25.0
pandas==2.3.3
pillow==11.3.0
propcache==0.4.0
protobuf==6.32.1
psutil==7.1.0
pyarrow==21.0.0
pydantic==2.12.0
pydantic-extra-types==2.10.5
pydantic-settings==2.11.0
pydantic_core==2.41.1
Pygments==2.19.2
pyparsing==3.2.5
python-dateutil==2.9.0.post0
python-dotenv==1.1.1
python-multipart==0.0.20
pytz==2025.2
PyYAML==6.0.3
regex==2025.9.18
requests==2.32.5
rich==14.1.0
rich-toolkit==0.15.1
rignore==0.7.0
safetensors==0.6.2
scikit-learn==1.7.2
scipy==1.16.2
sentence-transformers==5.1.1
sentry-sdk==2.40.0
setuptools==80.9.0
shellingham==1.5.4
six==1.17.0
sniffio==1.3.1
sqlite-vec==0.1.6
starlette==0.48.0
sympy==1.14.0
tensorboardX==2.6.4
threadpoolctl==3.6.0
tokenizers==0.22.1
torch==2.8.0
tqdm==4.67.1
transformers==4.57.0
triton==3.4.0
typer==0.19.2
typing-inspection==0.4.2
typing_extensions==4.15.0
tzdata==2025.2
ujson==5.11.0
urllib3==2.5.0
uvicorn==0.37.0
uvloop==0.21.0
watchfiles==1.1.0
websockets==15.0.1
xxhash==3.6.0
yarl==1.22.0

$ fastapi run citatio

   FastAPI   Starting production server 🚀

             Searching for package file structure from directories with __init__.py files
             Importing from /home/nils/repos/asmtransformers/citatio

    module   📁 citatio
             └── 🐍 __init__.py

      code   Importing the FastAPI app object from the module with the following code:

             from citatio import app

       app   Using import string: citatio:app

    server   Server started at http://0.0.0.0:8000
    server   Documentation at http://0.0.0.0:8000/docs

             Logs:

      INFO   Started server process [215318]
      INFO   Waiting for application startup.
The tokenizer class you load from this checkpoint is not the same type as the class this function is called from. It may result in unexpected tokenization.
The tokenizer class you load from this checkpoint is 'ARM64Tokenizer'.
The class this function is called from is 'BertTokenizer'.
      INFO   Application startup complete.
      INFO   Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
      INFO   127.0.0.1:41100 - "POST /api/v1/search HTTP/1.1" 500
     ERROR   Exception in ASGI application
Traceback (most recent call last):
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/uvicorn/protocols/http/httptools_impl.py", line 409, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        self.scope, self.receive, self.send
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/uvicorn/middleware/proxy_headers.py", line 60, in __call__
    return await self.app(scope, receive, send)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/fastapi/applications.py", line 1133, in __call__
    await super().__call__(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/applications.py", line 113, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/middleware/errors.py", line 186, in __call__
    raise exc
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/middleware/errors.py", line 164, in __call__
    await self.app(scope, receive, _send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/middleware/exceptions.py", line 63, in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/fastapi/middleware/asyncexitstack.py", line 18, in __call__
    await self.app(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/routing.py", line 716, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/routing.py", line 736, in app
    await route.handle(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/routing.py", line 290, in handle
    await self.app(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/fastapi/routing.py", line 123, in app
    await wrap_app_handling_exceptions(app, request)(scope, receive, send)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/fastapi/routing.py", line 109, in app
    response = await f(request)
               ^^^^^^^^^^^^^^^^
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/fastapi/routing.py", line 387, in app
    raw_response = await run_endpoint_function(
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<3 lines>...
    )
    ^
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/fastapi/routing.py", line 288, in run_endpoint_function
    return await dependant.call(**values)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/nils/repos/asmtransformers/citatio/citatio/api.py", line 54, in search_function
    embedding = request.app.state.model.encode(str(cfg))
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/asmtransformers/models/asmsentencebert.py", line 130, in encode
    return super().encode(sentences, *args, normalize_embeddings=normalize_embeddings, **kwargs)
           ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/torch/utils/_contextlib.py", line 120, in decorate_context
    return func(*args, **kwargs)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/sentence_transformers/SentenceTransformer.py", line 1094, in encode
    out_features = self.forward(features, **kwargs)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/sentence_transformers/SentenceTransformer.py", line 1175, in forward
    input = module(input, **module_kwargs)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/torch/nn/modules/module.py", line 1773, in _wrapped_call_impl
    return self._call_impl(*args, **kwargs)
           ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/torch/nn/modules/module.py", line 1784, in _call_impl
    return forward_call(*args, **kwargs)
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/sentence_transformers/models/Transformer.py", line 259, in forward
    trans_features = {key: value for key, value in features.items() if key in self.model_forward_params}
                                                                              ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/nils/repos/asmtransformers/.venv/lib/python3.13/site-packages/torch/nn/modules/module.py", line 1962, in __getattr__
    raise AttributeError(
        f"'{type(self).__name__}' object has no attribute '{name}'"
    )
AttributeError: 'ASMSTTransformer' object has no attribute 'model_forward_params'

[akaIDIOT]

Without having looked into it very far, the vibe here is to lock the dependency to <5.0 in the short term to make sure it works for you and anyone cloning this, and upgrade to 5.* for real later down the line.

[judithvdw]

According to the release notes of sentence transformers 5.* should be fully backwards compatible. But I am not sure if we should spend too much time on this right now so restricting to <5.0 is a good temporary solution as far as I am concerned. Upgrading when we continue with the project is probably going to be worth it anyways for the new features (such as training with multiple loss functions) we previously used workarounds for. https://github.com/UKPLab/sentence-transformers/releases/tag/v5.0.0