Performance: load a cached Hugging Face embedding model without contacting the Hub

Every chat question and AI suggestion request builds the embedding model, and sentence-transformers checks the Hub for a newer revision each time. With the model already cached that check cost about 2 seconds per request (0.2 seconds without it), and it fails outright when the Hub is unreachable.

Load from the local cache first and only download when the model is missing. A full rebuild still checks the Hub, so a new model release is picked up together with re-embedding every document instead of silently mixing revisions.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SRX1rCtSx62vSDaiFuBFCM

src-ui/messages.xlf

@@ -10334,18 +10334,18 @@
           <context context-type="linenumber">294,295</context>
         </context-group>
       </trans-unit>
-      <trans-unit id="2179847500064178686" datatype="html">
-        <source>Edit document</source>
+      <trans-unit id="3420321797707163677" datatype="html">
+        <source>Preview document</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/components/document-list/document-list.component.html</context>
           <context context-type="linenumber">328</context>
         </context-group>
       </trans-unit>
-      <trans-unit id="3420321797707163677" datatype="html">
-        <source>Preview document</source>
+      <trans-unit id="2179847500064178686" datatype="html">
+        <source>Edit document</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/components/document-list/document-list.component.html</context>
-          <context context-type="linenumber">329</context>
+          <context context-type="linenumber">331</context>
         </context-group>
       </trans-unit>
       <trans-unit id="4512084577073831437" datatype="html">

src-ui/src/app/components/document-detail/document-detail.component.html

@@ -465,7 +465,7 @@
     @switch (archiveContentRenderType) {
       @case (ContentRenderType.PDF) {
         @if (!useNativePdfViewer) {
-          <div class="preview-sticky pdf-viewer-container">
+          <div class="preview-sticky pdf-viewer-container" tabindex="-1">
             <pngx-pdf-viewer
               [src]="pdfSource()"
               [sourceRevision]="previewRevision()"
@@ -477,7 +477,7 @@
               (loadError)="onError($event)"
               (afterLoadComplete)="pdfPreviewLoaded($event)">
             </pngx-pdf-viewer>
-            <div class="position-absolute bottom-0 start-50 translate-middle-x z-1 mb-3 d-flex gap-2 p-1 bg-body border rounded shadow">
+            <div class="preview-controls position-absolute bottom-0 start-50 translate-middle-x z-1 mb-3 d-flex gap-2 p-1 bg-body border rounded shadow">
               @if (previewNumPages()) {
                 <div class="input-group input-group-sm w-auto flex-nowrap">
                   <input class="form-control flex-grow-0 w-auto" type="number" min="1" [max]="previewNumPages()" [ngModelOptions]="{standalone: true}" [ngModel]="previewCurrentPage()" (ngModelChange)="previewCurrentPage.set($event)" aria-label="Page" i18n-aria-label />

src-ui/src/app/components/document-detail/document-detail.component.scss

@@ -12,6 +12,22 @@
     width: 100%;
     height: 100%;
   }
+
+  &:focus {
+    outline: none;
+  }
+
+  .preview-controls {
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.15s ease-in-out;
+  }
+
+  &:hover .preview-controls,
+  &:focus-within .preview-controls {
+    opacity: 1;
+    pointer-events: auto;
+  }
 }
 
 .btn-group .dropdown-toggle-split {

src-ui/src/app/components/document-list/document-list.component.html

@@ -208,7 +208,7 @@
                   i18n>Correspondent</th>
               }
               @if (activeDisplayFields.includes(DisplayField.TITLE)) {
-                <th class="cursor-pointer"
+                <th class="cursor-pointer ps-5"
                   pngxSortable="title"
                   title="Sort by title" i18n-title
                   [currentSortField]="list.sortField"
@@ -322,13 +322,13 @@
                   </td>
                 }
                 @if (activeDisplayFields.includes(DisplayField.TITLE) || activeDisplayFields.includes(DisplayField.TAGS)) {
-                  <td width="30%">
+                  <td width="30%" class="position-relative" [class.ps-5]="activeDisplayFields.includes(DisplayField.TITLE)">
                     @if (activeDisplayFields.includes(DisplayField.TITLE)) {
                       <div class="d-inline-block" (mouseleave)="popupPreview.close()">
-                        <a routerLink="/documents/{{d.id}}" title="Edit document" i18n-title style="overflow-wrap: anywhere;">{{d.title | documentTitle}}</a>
-                        <pngx-preview-popup [document]="d" linkClasses="btn btn-sm btn-link text-secondary" linkTitle="Preview document" (click)="$event.stopPropagation()" i18n-linkTitle #popupPreview>
+                        <pngx-preview-popup class="position-absolute start-0" [document]="d" linkClasses="btn btn-sm btn-link text-secondary" linkTitle="Preview document" (click)="$event.stopPropagation()" i18n-linkTitle #popupPreview>
                           <i-bs name="eye"></i-bs>
                         </pngx-preview-popup>
+                        <a routerLink="/documents/{{d.id}}" title="Edit document" i18n-title style="overflow-wrap: anywhere;">{{d.title | documentTitle}}</a>
                       </div>
                     }
                     @if (activeDisplayFields.includes(DisplayField.TAGS)) {

src-ui/src/app/components/document-list/document-list.component.scss

@@ -87,6 +87,10 @@ $paperless-card-breakpoints: (
   }
 }
 
+.table .ps-5 {
+  padding-left: 2.2rem !important;
+}
+
 a {
   cursor: pointer;
 }

src/conftest.py

@@ -77,30 +77,6 @@ def _clear_django_caches() -> None:
         cache.clear()
 
 
-@pytest.fixture(autouse=True)
-def _keep_connection_open_in_atomic(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Make ``close_old_connections()`` a no-op inside the test's transaction.
-
-    The Celery signal handlers call it, as a worker would between tasks. Tests
-    run inside an open atomic block, where Postgres really closes the
-    connection, taking the test transaction and every later test on the
-    worker with it. SQLite in-memory ignores the close, which hid this.
-    """
-    from django.db.backends.base.base import BaseDatabaseWrapper
-
-    original = BaseDatabaseWrapper.close_if_unusable_or_obsolete
-
-    def close_unless_atomic(self: BaseDatabaseWrapper) -> None:
-        if not self.in_atomic_block:
-            original(self)
-
-    monkeypatch.setattr(
-        BaseDatabaseWrapper,
-        "close_if_unusable_or_obsolete",
-        close_unless_atomic,
-    )
-
-
 @pytest.fixture
 def paperless_dirs(
     tmp_path: Path,

src/documents/matching.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 import re
 from fnmatch import fnmatch
+from fnmatch import translate as fnmatch_translate
 from typing import TYPE_CHECKING
 
 from rest_framework import serializers
@@ -547,48 +548,6 @@ def existing_document_matches_workflow(
     return (True, None)
 
 
-def glob_to_database_regex(pattern: str) -> str:
-    """
-    Translates an fnmatch style glob into a regular expression which the
-    database can evaluate, matching the whole value.
-
-    fnmatch.translate is not usable here: it emits syntax such as (?s:...),
-    atomic groups and named group backreferences, which PostgreSQL rejects.
-    Only constructs common to Python, PostgreSQL and MariaDB are produced.
-    """
-    parts: list[str] = []
-    i = 0
-    n = len(pattern)
-    while i < n:
-        char = pattern[i]
-        i += 1
-        if char == "*":
-            parts.append(".*")
-        elif char == "?":
-            parts.append(".")
-        elif char == "[":
-            j = i
-            if j < n and pattern[j] == "!":
-                j += 1
-            if j < n and pattern[j] == "]":
-                j += 1
-            while j < n and pattern[j] != "]":
-                j += 1
-            if j >= n:
-                parts.append(r"\[")
-            else:
-                stuff = pattern[i:j].replace("\\", r"\\").replace("[", r"\[")
-                i = j + 1
-                if stuff.startswith("!"):
-                    stuff = "^" + stuff[1:]
-                elif stuff.startswith("^"):
-                    stuff = "\\" + stuff
-                parts.append(f"[{stuff}]")
-        else:
-            parts.append(re.escape(char))
-    return "^" + "".join(parts) + "$"
-
-
 def prefilter_documents_by_workflowtrigger(
     documents: QuerySet[Document],
     trigger: WorkflowTrigger,
@@ -669,9 +628,8 @@ def prefilter_documents_by_workflowtrigger(
         documents = documents.annotate(**annotations).filter(custom_field_q)
 
     if trigger.filter_filename:
-        documents = documents.filter(
-            original_filename__iregex=glob_to_database_regex(trigger.filter_filename),
-        )
+        regex = fnmatch_translate(trigger.filter_filename).lstrip("^").rstrip("$")
+        documents = documents.filter(original_filename__iregex=regex)
 
     return documents
 

src/documents/tests/test_api_custom_fields.py

@@ -1062,7 +1062,7 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
                 "custom_fields": [
                     {
                         "field": custom_field_doclink.id,
-                        "value": [doc2.id, doc3.id, doc4.id],
+                        "value": [2, 3, 4],
                     },
                 ],
             },
@@ -1073,13 +1073,13 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
         self.assertEqual(CustomFieldInstance.objects.count(), 4)
         _cf_5 = doc2.custom_fields.first()
         assert _cf_5 is not None
-        self.assertEqual(_cf_5.value, [doc1.id])
+        self.assertEqual(_cf_5.value, [1])
         _cf_6 = doc3.custom_fields.first()
         assert _cf_6 is not None
-        self.assertEqual(_cf_6.value, [doc1.id])
+        self.assertEqual(_cf_6.value, [1])
         _cf_7 = doc4.custom_fields.first()
         assert _cf_7 is not None
-        self.assertEqual(_cf_7.value, [doc1.id])
+        self.assertEqual(_cf_7.value, [1])
 
         # Add links appends if necessary
         resp = self.client.patch(
@@ -1088,7 +1088,7 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
                 "custom_fields": [
                     {
                         "field": custom_field_doclink.id,
-                        "value": [doc1.id, doc4.id],
+                        "value": [1, 4],
                     },
                 ],
             },
@@ -1098,7 +1098,7 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
         self.assertEqual(resp.status_code, status.HTTP_200_OK)
         _cf_8 = doc4.custom_fields.first()
         assert _cf_8 is not None
-        self.assertEqual(_cf_8.value, [doc1.id, doc3.id])
+        self.assertEqual(_cf_8.value, [1, 3])
 
         # Remove one of the links, removed on other doc
         resp = self.client.patch(
@@ -1107,7 +1107,7 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
                 "custom_fields": [
                     {
                         "field": custom_field_doclink.id,
-                        "value": [doc2.id, doc3.id],
+                        "value": [2, 3],
                     },
                 ],
             },
@@ -1117,13 +1117,13 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
         self.assertEqual(resp.status_code, status.HTTP_200_OK)
         _cf_9 = doc2.custom_fields.first()
         assert _cf_9 is not None
-        self.assertEqual(_cf_9.value, [doc1.id])
+        self.assertEqual(_cf_9.value, [1])
         _cf_10 = doc3.custom_fields.first()
         assert _cf_10 is not None
-        self.assertEqual(_cf_10.value, [doc1.id, doc4.id])
+        self.assertEqual(_cf_10.value, [1, 4])
         _cf_11 = doc4.custom_fields.first()
         assert _cf_11 is not None
-        self.assertEqual(_cf_11.value, [doc3.id])
+        self.assertEqual(_cf_11.value, [3])
 
         # Removes the field entirely
         resp = self.client.patch(
@@ -1140,10 +1140,10 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
         self.assertEqual(_cf_12.value, [])
         _cf_13 = doc3.custom_fields.first()
         assert _cf_13 is not None
-        self.assertEqual(_cf_13.value, [doc4.id])
+        self.assertEqual(_cf_13.value, [4])
         _cf_14 = doc4.custom_fields.first()
         assert _cf_14 is not None
-        self.assertEqual(_cf_14.value, [doc3.id])
+        self.assertEqual(_cf_14.value, [3])
 
         # If field exists on target doc but value is None
         doc5 = Document.objects.create(
@@ -1170,7 +1170,7 @@ class TestCustomFieldsAPI(DirectoriesMixin, APITestCase):
         self.assertEqual(resp.status_code, status.HTTP_200_OK)
         _cf_15 = doc5.custom_fields.first()
         assert _cf_15 is not None
-        self.assertEqual(_cf_15.value, [doc1.id])
+        self.assertEqual(_cf_15.value, [1])
 
     def test_documentlink_patch_requires_change_permission_on_target_documents(
         self,

src/documents/tests/test_api_filter_by_custom_fields.py

@@ -6,7 +6,6 @@ from unittest.mock import patch
 from urllib.parse import quote
 
 import time_machine
-from django.db import connection
 from django.test import override_settings
 from django.utils import timezone
 from rest_framework.test import APITestCase
@@ -21,13 +20,6 @@ from paperless_testing.dirs import DirectoriesMixin
 from paperless_testing.factories import UserFactory
 
 
-def _exact_equal(value: str | None, expected: str) -> bool:
-    """`exact` follows the column collation, which is case insensitive on MariaDB."""
-    if connection.vendor == "mysql" and value is not None:
-        return value.casefold() == expected.casefold()
-    return value == expected
-
-
 class DocumentWrapper:
     """
     Allows Pythonic access to the custom fields associated with the wrapped document.
@@ -295,8 +287,7 @@ class TestCustomFieldsSearch(DirectoriesMixin, APITestCase):
         self._assert_query_match_predicate(
             ["string_field", "exact", "paperless"],
             lambda document: (
-                "string_field" in document
-                and _exact_equal(document["string_field"], "paperless")
+                "string_field" in document and document["string_field"] == "paperless"
             ),
         )
 
@@ -305,10 +296,7 @@ class TestCustomFieldsSearch(DirectoriesMixin, APITestCase):
             ["string_field", "in", ["paperless", "Paperless"]],
             lambda document: (
                 "string_field" in document
-                and any(
-                    _exact_equal(document["string_field"], expected)
-                    for expected in ("paperless", "Paperless")
-                )
+                and document["string_field"] in ("paperless", "Paperless")
             ),
         )
 
@@ -640,23 +628,22 @@ class TestCustomFieldsSearch(DirectoriesMixin, APITestCase):
     # Subset check (document link field only)                   #
     # ==========================================================#
     def test_document_link_contains(self) -> None:
-        linked = {self.documents[1].id, self.documents[2].id}
         # Document link field "contains" performs a subset check.
         self._assert_query_match_predicate(
-            ["documentlink_field", "contains", sorted(linked)],
+            ["documentlink_field", "contains", [1, 2]],
             lambda document: (
                 "documentlink_field" in document
                 and document["documentlink_field"] is not None
-                and set(document["documentlink_field"]) >= linked
+                and set(document["documentlink_field"]) >= {1, 2}
             ),
         )
         # The order of IDs don't matter - this is the same as above.
         self._assert_query_match_predicate(
-            ["documentlink_field", "contains", sorted(linked, reverse=True)],
+            ["documentlink_field", "contains", [2, 1]],
             lambda document: (
                 "documentlink_field" in document
                 and document["documentlink_field"] is not None
-                and set(document["documentlink_field"]) >= linked
+                and set(document["documentlink_field"]) >= {1, 2}
             ),
         )
 
@@ -773,7 +760,7 @@ class TestCustomFieldsSearch(DirectoriesMixin, APITestCase):
             lambda document: (
                 not (
                     "string_field" in document
-                    and _exact_equal(document["string_field"], "paperless")
+                    and document["string_field"] == "paperless"
                 )
             ),
         )

src/documents/tests/test_api_search.py

@@ -944,7 +944,7 @@ class TestDocumentSearchApi(DirectoriesMixin, APITestCase):
         self.assertEqual(response.status_code, status.HTTP_200_OK)
 
         results = response.data["results"]
-        self.assertEqual({r["id"] for r in results}, {d1.id, d2.id})
+        self.assertEqual({r["id"] for r in results}, {1, 2})
 
     @mock.patch("documents.search._backend.parse_user_query")
     def test_search_parser_bug_surfaces_as_500_not_400(self, m) -> None:
@@ -1801,7 +1801,6 @@ class TestDocumentSearchApi(DirectoriesMixin, APITestCase):
     def test_search_sorting(self) -> None:
         u1 = UserFactory(username="user1")
         u2 = UserFactory(username="user2")
-        u3 = UserFactory(username="user3")
         c1 = Correspondent.objects.create(name="corres Ax")
         c2 = Correspondent.objects.create(name="corres Cx")
         c3 = Correspondent.objects.create(name="corres Bx")
@@ -1827,7 +1826,6 @@ class TestDocumentSearchApi(DirectoriesMixin, APITestCase):
             content="test",
             archive_serial_number=1,
             title="1",
-            owner=u3,
         )
         Note.objects.create(
             note="This is a note.",
@@ -1880,14 +1878,14 @@ class TestDocumentSearchApi(DirectoriesMixin, APITestCase):
             search_query("&ordering=-num_notes"),
             [d1.id, d3.id, d2.id],
         )
-        # owner sort: ORM orders by owner_id (integer)
+        # owner sort: ORM orders by owner_id (integer); NULLs first in SQLite ASC
         self.assertListEqual(
             search_query("&ordering=owner"),
-            [d1.id, d2.id, d3.id],
+            [d3.id, d1.id, d2.id],
         )
         self.assertListEqual(
             search_query("&ordering=-owner"),
-            [d3.id, d2.id, d1.id],
+            [d2.id, d1.id, d3.id],
         )
 
     def test_search_ordering_by_score(self) -> None:

src/documents/tests/test_api_status.py

@@ -5,7 +5,6 @@ from datetime import timedelta
 from pathlib import Path
 from unittest import mock
 
-from django.db import connection
 from django.test import override_settings
 from django.utils import timezone
 from rest_framework import status
@@ -69,7 +68,7 @@ class TestSystemStatus(APITestCase):
         self.assertEqual(response.data["install_type"], "bare-metal")
         self.assertIsNotNone(response.data["storage"]["total"])
         self.assertIsNotNone(response.data["storage"]["available"])
-        self.assertEqual(response.data["database"]["type"], connection.vendor)
+        self.assertEqual(response.data["database"]["type"], "sqlite")
         self.assertIsNotNone(response.data["database"]["url"])
         self.assertEqual(response.data["database"]["status"], "OK")
         self.assertIsNone(response.data["database"]["error"])

src/documents/tests/test_bulk_edit.py

@@ -1031,7 +1031,9 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         with self.assertLogs("paperless.bulk_edit", level="ERROR") as cm:
             bulk_edit.merge(doc_ids)
             error_str = cm.output[0]
-            expected_str = f"Error merging document {self.doc2.id}, it will not be included in the merge"
+            expected_str = (
+                "Error merging document 2, it will not be included in the merge"
+            )
             self.assertIn(expected_str, error_str)
 
         mock_consume_file.assert_not_called()
@@ -1191,7 +1193,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         with self.assertLogs("paperless.bulk_edit", level="ERROR") as cm:
             bulk_edit.split(doc_ids, pages)
             error_str = cm.output[0]
-            expected_str = f"Error splitting document {self.doc2.id}"
+            expected_str = "Error splitting document 2"
             self.assertIn(expected_str, error_str)
 
         mock_consume_file.assert_not_called()

src/documents/tests/test_consumer.py

@@ -248,8 +248,8 @@ class TestConsumer(
         )
         self.assertIsNone(document.correspondent)
         self.assertIsNone(document.document_type)
-        self.assertEqual(document.filename, f"{document.pk:07}.pdf")
-        self.assertEqual(document.archive_filename, f"{document.pk:07}.pdf")
+        self.assertEqual(document.filename, "0000001.pdf")
+        self.assertEqual(document.archive_filename, "0000001.pdf")
 
         self.assertIsFile(document.source_path)
 
@@ -1127,17 +1127,17 @@ class TestConsumer(
         with self.get_consumer(settings.CONSUMPTION_DIR / "simple.png") as consumer:
             consumer.run()
 
-            doc1 = Document.objects.latest("pk")
+            doc1 = Document.objects.filter(pk=1).first()
 
         with self.get_consumer(settings.CONSUMPTION_DIR / "simple.pdf") as consumer:
             consumer.run()
 
-            doc2 = Document.objects.latest("pk")
+            doc2 = Document.objects.filter(pk=2).first()
 
         with self.get_consumer(settings.CONSUMPTION_DIR / "simple.png.pdf") as consumer:
             consumer.run()
 
-            doc3 = Document.objects.latest("pk")
+            doc3 = Document.objects.filter(pk=3).first()
 
         self.assertEqual(doc1.filename, "simple.png")
         self.assertEqual(doc1.archive_filename, "simple.pdf")

src/documents/tests/test_document_list_effective_content_annotation.py

@@ -242,7 +242,9 @@ class TestDocumentListEffectiveContentAnnotation:
         # Only the list query itself reads a content column: no extra query
         # for the skipped prefetch, none for a per-instance fallback
         content_queries = [
-            query for query in ctx.captured_queries if _content_column() in query["sql"]
+            query
+            for query in ctx.captured_queries
+            if '"documents_document"."content"' in query["sql"]
         ]
         assert len(content_queries) == 1
 
@@ -363,11 +365,6 @@ def _get_document_queries(
     return [q for q in ctx.captured_queries if '"django_content_type"' not in q["sql"]]
 
 
-def _content_column() -> str:
-    quote = connection.ops.quote_name
-    return f"{quote('documents_document')}.{quote('content')}"
-
-
 def _get_effective_content_fallback_queries(
     ctx: CaptureQueriesContext,
 ) -> list[dict[str, str]]:
@@ -382,7 +379,7 @@ def _get_effective_content_fallback_queries(
     return [
         q
         for q in ctx.captured_queries
-        if q["sql"].startswith(f"SELECT {_content_column()} FROM")
+        if q["sql"].startswith('SELECT "documents_document"."content" FROM')
     ]
 
 

src/documents/tests/test_file_handling.py

@@ -760,9 +760,6 @@ class TestFileHandlingWithArchive(DirectoriesMixin, FileSystemAssertsMixin, Test
             archive_checksum="B",
         )
 
-        # Without a format the files are renamed to match the primary key
-        original = doc.source_path
-        archive = doc.archive_path
         self.assertIsFile(original)
         self.assertIsFile(archive)
         self.assertIsFile(doc.source_path)
@@ -981,9 +978,6 @@ class TestFileHandlingWithArchive(DirectoriesMixin, FileSystemAssertsMixin, Test
             archive_filename="0000001.pdf",
         )
 
-        # Without a format the files are renamed to match the primary key
-        original = doc.source_path
-        archive = doc.archive_path
         self.assertIsFile(original)
         self.assertIsFile(archive)
         self.assertIsFile(doc.source_path)

src/documents/tests/test_management_exporter.py

@@ -151,20 +151,6 @@ class TestExportImport(
 
         super().setUp()
 
-    def _install_sample_files(self) -> None:
-        documents_dir = Path(self.dirs.media_dir) / "documents"
-        shutil.rmtree(documents_dir)
-        install_document_samples(documents_dir)
-        # Thumbnails are located by primary key, which the database sequence
-        # does not reset between tests on PostgreSQL
-        for number, document in enumerate(
-            (self.d1, self.d2, self.d3, self.d4),
-            start=1,
-        ):
-            source = documents_dir / "thumbnails" / f"{number:07}.webp"
-            if source != document.thumbnail_path:
-                shutil.copy(source, document.thumbnail_path)
-
     def _get_document_from_manifest(self, manifest, id):
         f = list(
             filter(
@@ -218,7 +204,8 @@ class TestExportImport(
         return manifest
 
     def test_exporter(self, *, use_filename_format=False) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         num_permission_objects = Permission.objects.count()
 
@@ -321,7 +308,8 @@ class TestExportImport(
             self.assertEqual(messages.total_issue_count, 0)
 
     def test_exporter_with_filename_format(self) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         with override_settings(
             FILENAME_FORMAT="{created_year}/{correspondent}/{title}",
@@ -329,7 +317,8 @@ class TestExportImport(
             self.test_exporter(use_filename_format=True)
 
     def test_exporter_includes_share_links_and_bundles(self) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         share_link = ShareLink.objects.create(
             slug="share-link-slug",
@@ -427,7 +416,8 @@ class TestExportImport(
             )
 
     def test_update_export_changed_time(self) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export()
         self.assertIsFile(self.target / "manifest.json")
@@ -462,7 +452,8 @@ class TestExportImport(
         self.assertEqual(st_mtime_3, st_mtime_4)
 
     def test_update_export_changed_checksum(self) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export()
 
@@ -488,7 +479,8 @@ class TestExportImport(
         self.assertIsFile(self.target / "manifest.json")
 
     def test_update_export_deleted_document(self) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export()
 
@@ -519,7 +511,8 @@ class TestExportImport(
 
     @override_settings(FILENAME_FORMAT="{title}/{correspondent}")
     def test_update_export_changed_location(self) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export(use_filename_format=True)
         self.assertIsFile(self.target / "wow1" / "c.pdf")
@@ -560,7 +553,8 @@ class TestExportImport(
             - Zipfile is created
             - Zipfile contains exported files
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         args = ["document_exporter", self.target, "--zip"]
 
@@ -588,7 +582,8 @@ class TestExportImport(
             - Zipfile is created
             - Zipfile contains exported files
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         args = ["document_exporter", self.target, "--zip", "--use-filename-format"]
 
@@ -623,7 +618,8 @@ class TestExportImport(
             - Zipfile contains exported files
             - The existing file and directory in target are removed
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         # Create stuff in target directory
         existing_file = self.target / "test.txt"
@@ -718,7 +714,8 @@ class TestExportImport(
             - Manifest.json doesn't contain information about archive files
             - Documents can be imported again
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export()
         has_archive = False
@@ -760,7 +757,8 @@ class TestExportImport(
             - Manifest.json doesn't contain information about thumbnails
             - Documents can be imported again
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export()
         has_thumbnail = False
@@ -804,7 +802,8 @@ class TestExportImport(
             - Main manifest.json file doesn't contain information about documents
             - Documents can be imported again
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export(split_manifest=True)
         has_document = False
@@ -828,7 +827,8 @@ class TestExportImport(
             self.assertEqual(CustomFieldInstance.objects.count(), 1)
 
     def _export_import_barcodes(self, *, split_manifest: bool) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
         DocumentBarcodeFactory(document=self.d1, value="https://example.com")
         DocumentBarcodeFactory(document=self.d2, page=2, value="DE8937")
 
@@ -863,7 +863,8 @@ class TestExportImport(
         THEN:
             - Documents can be imported again
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export(use_folder_prefix=True)
 
@@ -889,7 +890,8 @@ class TestExportImport(
         THEN:
             - Documents can be imported again
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export(use_folder_prefix=True, split_manifest=True)
 
@@ -915,7 +917,8 @@ class TestExportImport(
             - ContentType & Permission objects are not deleted, db transaction rolled back
         """
 
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         num_content_type_objects = ContentType.objects.count()
         num_permission_objects = Permission.objects.count()
@@ -951,7 +954,8 @@ class TestExportImport(
             self.assertEqual(Permission.objects.count(), num_permission_objects + 1)
 
     def test_exporter_with_auditlog_disabled(self) -> None:
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         with override_settings(
             AUDIT_LOG_ENABLED=False,
@@ -970,7 +974,8 @@ class TestExportImport(
             - The soft-deleted document, note, and custom field instance
               survive the round-trip with deleted_at preserved
         """
-        self._install_sample_files()
+        shutil.rmtree(Path(self.dirs.media_dir) / "documents")
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         # d1 has self.note and self.cfi1 attached via setUp
         self.d1.delete()

src/documents/tests/test_management_fuzzy.py

@@ -19,10 +19,6 @@ class TestFuzzyMatchCommand(TestCase):
         call_command(
             "document_fuzzy_match",
             "--no-progress-bar",
-            # The default scales with the CPU count and forks, which closes
-            # the test's database connection on PostgreSQL
-            "--processes",
-            "1",
             *args,
             stdout=stdout,
             stderr=stderr,

src/documents/tests/test_management_retagger.py

@@ -425,29 +425,26 @@ class TestRetaggerStoragePath(DirectoriesMixin):
 @pytest.mark.management
 @pytest.mark.django_db
 class TestRetaggerIdRange(DirectoriesMixin):
+    @pytest.mark.usefixtures("documents")
     @pytest.mark.parametrize(
-        ("range_end", "expected_count"),
+        ("id_range_args", "expected_count"),
         [
-            pytest.param("second", 1, id="narrow_range_limits_scope"),
-            pytest.param("extra", 2, id="wide_range_tags_all_matches"),
+            pytest.param(["1", "2"], 1, id="narrow_range_limits_scope"),
+            pytest.param(["1", "9999"], 2, id="wide_range_tags_all_matches"),
         ],
     )
     def test_id_range_limits_scope(
         self,
         tags: TagTuple,
-        documents: DocumentTuple,
-        range_end: str,
+        id_range_args: list[str],
         expected_count: int,
     ) -> None:
-        first, second, *_ = documents
-        extra = DocumentFactory(content="NOT the first document")
-        end = {"second": second, "extra": extra}[range_end]
+        DocumentFactory(content="NOT the first document")
         call_command(
             "document_retagger",
             "--tags",
             "--id-range",
-            str(first.pk),
-            str(end.pk),
+            *id_range_args,
             skip_checks=True,
         )
         tag_first, *_ = tags

src/documents/tests/test_matching_glob_regex.py

@@ -1,68 +0,0 @@
-import re
-from fnmatch import fnmatch
-
-import pytest
-
-from documents.matching import glob_to_database_regex
-from documents.models import Document
-from paperless_testing.factories import DocumentFactory
-
-NAMES = [
-    "invoice.pdf",
-    "Invoice.PDF",
-    "invoice_2024.pdf",
-    "a.b.c",
-    "a-b",
-    "sample [1].pdf",
-    "sample 1.pdf",
-    "x^y",
-    "back\\slash",
-    "dir/file.pdf",
-    "",
-]
-
-PATTERNS = [
-    "*",
-    "invoice.pdf",
-    "*.pdf",
-    "*invoice*pdf",
-    "*a*b*c*",
-    "invoice_????.pdf",
-    "sample [[]1].pdf",
-    "sample [1-2].pdf",
-    "sample [!2].pdf",
-    "sample [^2].pdf",
-    "sample [",
-    "a.b.c",
-    "x^y",
-    "back\\slash",
-    "[]]",
-]
-
-
-@pytest.mark.parametrize("pattern", PATTERNS)
-def test_regex_agrees_with_fnmatch(pattern: str) -> None:
-    regex = glob_to_database_regex(pattern)
-    for name in NAMES:
-        expected = fnmatch(name.lower(), pattern.lower())
-        actual = re.search(regex, name, re.IGNORECASE) is not None
-        assert actual is expected, f"{pattern!r} vs {name!r}"
-
-
-@pytest.mark.parametrize("pattern", ["*", "*a*b*c*", "a*b*c*d*e"])
-def test_regex_avoids_syntax_postgresql_rejects(pattern: str) -> None:
-    regex = glob_to_database_regex(pattern)
-    assert not any(marker in regex for marker in ("(?", "\\Z"))
-
-
-@pytest.mark.django_db
-def test_database_filter_matches_glob() -> None:
-    matching = DocumentFactory(original_filename="Invoice_2024.PDF")
-    DocumentFactory(original_filename="invoice_2024.txt")
-    DocumentFactory(original_filename="receipt.pdf")
-
-    found = Document.objects.filter(
-        original_filename__iregex=glob_to_database_regex("*invoice*.pdf"),
-    )
-
-    assert list(found) == [matching]

src/documents/tests/test_workflows.py

@@ -174,8 +174,8 @@ class TestWorkflows(
         w.save()
 
         self.assertEqual(w.__str__(), "Workflow: Workflow 1")
-        self.assertEqual(trigger.__str__(), f"WorkflowTrigger {trigger.pk}")
-        self.assertEqual(action.__str__(), f"WorkflowAction {action.pk}")
+        self.assertEqual(trigger.__str__(), "WorkflowTrigger 1")
+        self.assertEqual(action.__str__(), "WorkflowAction 1")
 
         test_file = shutil.copy(
             self.SIMPLE_PDF,
@@ -433,7 +433,7 @@ class TestWorkflows(
                 list(document.tags.all()),
                 [self.t1, self.t2, self.t3],
             )
-            self.assertCountEqual(
+            self.assertEqual(
                 list(
                     get_users_with_perms(
                         document,

src/paperless_ai/embedding.py

@@ -20,7 +20,18 @@ OCR_LEADER_REGEX = re.compile(r"[._\-\u00b7]{4,}")
 HORIZONTAL_WHITESPACE_REGEX = re.compile(r"[ \t\u00a0]+")
 
 
-def get_embedding_model(config: AIConfig) -> "BaseEmbedding":
+def get_embedding_model(
+    config: AIConfig,
+    *,
+    refresh: bool = False,
+) -> "BaseEmbedding":
+    """Build the configured embedding model.
+
+    For the Hugging Face backend, a model already in the local cache is loaded
+    without contacting the Hub, which saves seconds per call. ``refresh=True``
+    checks the Hub for a newer revision first; index rebuilds use it so a new
+    model release is picked up together with re-embedding every document.
+    """
     match config.llm_embedding_backend:
         case LLMEmbeddingBackend.OPENAI_LIKE:
             from llama_index.embeddings.openai_like import OpenAILikeEmbedding
@@ -52,11 +63,18 @@ def get_embedding_model(config: AIConfig) -> "BaseEmbedding":
         case LLMEmbeddingBackend.HUGGINGFACE:
             from llama_index.embeddings.huggingface import HuggingFaceEmbedding
 
-            return HuggingFaceEmbedding(
-                model_name=config.llm_embedding_model
+            hf_kwargs = {
+                "model_name": config.llm_embedding_model
                 or "sentence-transformers/all-MiniLM-L6-v2",
-                cache_folder=str(settings.DATA_DIR / "hf_cache"),
-            )
+                "cache_folder": str(settings.DATA_DIR / "hf_cache"),
+            }
+            if refresh:
+                return HuggingFaceEmbedding(**hf_kwargs)
+            try:
+                return HuggingFaceEmbedding(**hf_kwargs, local_files_only=True)
+            except OSError:
+                # Not cached yet, download it
+                return HuggingFaceEmbedding(**hf_kwargs)
         case LLMEmbeddingBackend.OLLAMA:
             from llama_index.embeddings.ollama import OllamaEmbedding
             from ollama import AsyncClient

src/paperless_ai/indexing.py

@@ -470,7 +470,7 @@ def update_llm_index(
         logger.warning("No documents found to index.")
 
     chunk_size = config.llm_embedding_chunk_size
-    embed_model = get_embedding_model(config)
+    embed_model = get_embedding_model(config, refresh=rebuild)
 
     with write_store(embed_model_name=model_name) as store:
         if rebuild or not store.table_exists():

src/paperless_ai/tests/test_chat.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-from contextlib import nullcontext
 from typing import TYPE_CHECKING
 from typing import Any
 from unittest.mock import MagicMock
@@ -38,13 +37,6 @@ def patch_embed_model():
     llama_settings.Settings.embed_model = None
 
 
-@pytest.fixture(autouse=True)
-def keep_db_connection():
-    # Closing the connection would roll back the test's transaction on PostgreSQL
-    with patch("paperless_ai.chat.db_connection_released", nullcontext):
-        yield
-
-
 @pytest.fixture(autouse=True)
 def patch_embed_nodes():
     with patch(

src/paperless_ai/tests/test_embedding.py

@@ -167,6 +167,7 @@ def test_get_embedding_model_huggingface(mock_ai_config):
         MockHuggingFaceEmbedding.assert_called_once_with(
             model_name="sentence-transformers/all-MiniLM-L6-v2",
             cache_folder=str(settings.DATA_DIR / "hf_cache"),
+            local_files_only=True,
         )
         assert model == MockHuggingFaceEmbedding.return_value
 

src/paperless_ai/tests/test_embedding_hf_local_files.py

@@ -0,0 +1,106 @@
+from pathlib import Path
+from unittest.mock import MagicMock
+from unittest.mock import call
+from unittest.mock import patch
+
+import pytest
+import pytest_mock
+from django.conf import settings
+
+from paperless.models import LLMEmbeddingBackend
+from paperless_ai import indexing
+from paperless_ai.embedding import get_embedding_model
+from paperless_ai.tests.conftest import FakeEmbedding
+from paperless_testing.factories import DocumentFactory
+
+MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+CACHE = str(settings.DATA_DIR / "hf_cache")
+
+
+@pytest.fixture
+def hf_config() -> MagicMock:
+    config = MagicMock()
+    config.llm_embedding_backend = LLMEmbeddingBackend.HUGGINGFACE
+    config.llm_embedding_model = MODEL
+    return config
+
+
+@pytest.fixture
+def hf_embedding(mocker: pytest_mock.MockerFixture) -> MagicMock:
+    return mocker.patch("llama_index.embeddings.huggingface.HuggingFaceEmbedding")
+
+
+class TestHuggingFaceLocalFirst:
+    def test_uses_cached_model_without_hub(
+        self,
+        hf_config: MagicMock,
+        hf_embedding: MagicMock,
+    ) -> None:
+        model = get_embedding_model(hf_config)
+
+        hf_embedding.assert_called_once_with(
+            model_name=MODEL,
+            cache_folder=CACHE,
+            local_files_only=True,
+        )
+        assert model is hf_embedding.return_value
+
+    def test_downloads_when_not_cached(
+        self,
+        hf_config: MagicMock,
+        hf_embedding: MagicMock,
+    ) -> None:
+        downloaded = MagicMock()
+        hf_embedding.side_effect = [OSError("not cached"), downloaded]
+
+        model = get_embedding_model(hf_config)
+
+        assert hf_embedding.call_args_list == [
+            call(model_name=MODEL, cache_folder=CACHE, local_files_only=True),
+            call(model_name=MODEL, cache_folder=CACHE),
+        ]
+        assert model is downloaded
+
+    def test_refresh_checks_the_hub(
+        self,
+        hf_config: MagicMock,
+        hf_embedding: MagicMock,
+    ) -> None:
+        get_embedding_model(hf_config, refresh=True)
+
+        hf_embedding.assert_called_once_with(model_name=MODEL, cache_folder=CACHE)
+
+
+@pytest.mark.django_db
+class TestIndexUpdateRefresh:
+    @pytest.fixture(autouse=True)
+    def _index_inputs(self, temp_llm_index_dir: Path) -> None:
+        DocumentFactory.create()
+
+    def _update(self, mock_embed_model: FakeEmbedding, *, rebuild: bool) -> MagicMock:
+        mock_config = MagicMock()
+        mock_config.llm_embedding_chunk_size = 512
+        with (
+            patch("paperless_ai.indexing.AIConfig", return_value=mock_config),
+            patch("paperless_ai.indexing.build_document_node", return_value=[]),
+            patch(
+                "paperless_ai.indexing.get_embedding_model",
+                return_value=mock_embed_model,
+            ) as get_model,
+        ):
+            indexing.update_llm_index(rebuild=rebuild)
+        get_model.assert_called_once()
+        return get_model
+
+    def test_rebuild_refreshes(self, mock_embed_model: FakeEmbedding) -> None:
+        get_model = self._update(mock_embed_model, rebuild=True)
+
+        assert get_model.call_args.kwargs == {"refresh": True}
+
+    def test_incremental_update_stays_local(
+        self,
+        mock_embed_model: FakeEmbedding,
+    ) -> None:
+        get_model = self._update(mock_embed_model, rebuild=False)
+
+        assert get_model.call_args.kwargs == {"refresh": False}