Performance: replace django-treenode with adjacency-list tags

Co-Authored-By: Codex <267193182+codex@users.noreply.github.com>

docker/rootfs/etc/s6-overlay/s6-rc.d/init-compile-bytecode/run

@@ -39,7 +39,6 @@ declare -a scope=(
 	"${site_packages}/allauth"
 	"${site_packages}/drf_spectacular"
 	"${site_packages}/drf_spectacular_sidecar"
-	"${site_packages}/treenode"
 	"${site_packages}/compression_middleware"
 )
 

pyproject.toml

@@ -38,7 +38,6 @@ dependencies = [
   "django-multiselectfield~=1.0.1",
   "django-rich~=2.2.0",
   "django-soft-delete~=1.0.18",
-  "django-treenode>=0.24",
   "djangorestframework~=3.16",
   "drf-spectacular~=0.30",
   "drf-spectacular-sidecar>=2026.7.1,<2026.10",

src/documents/admin.py

@@ -1,7 +1,6 @@
 from django.conf import settings
 from django.contrib import admin
 from guardian.admin import GuardedModelAdmin
-from treenode.admin import TreeNodeModelAdmin
 
 from documents.models import Correspondent
 from documents.models import CustomField
@@ -29,7 +28,7 @@ class CorrespondentAdmin(GuardedModelAdmin):
     list_editable = ("match", "matching_algorithm")
 
 
-class TagAdmin(GuardedModelAdmin, TreeNodeModelAdmin):
+class TagAdmin(GuardedModelAdmin):
     list_display = ("name", "color", "match", "matching_algorithm")
     list_filter = ("matching_algorithm",)
     list_editable = ("color", "match", "matching_algorithm")

src/documents/barcodes.py

@@ -10,6 +10,9 @@ from typing import TYPE_CHECKING
 import regex as regex_mod
 from django.conf import settings
 from pdf2image import convert_from_path
+from pikepdf import Page
+from pikepdf import PasswordError
+from pikepdf import Pdf
 
 from documents.converters import convert_from_tiff_to_pdf
 from documents.data_models import ConsumableDocument
@@ -31,7 +34,6 @@ from documents.utils import maybe_override_pixel_limit
 from paperless.config import BarcodeConfig
 
 if TYPE_CHECKING:
-    from pikepdf import Page
     from PIL import Image
 
 logger = logging.getLogger("paperless.barcodes")
@@ -280,8 +282,6 @@ class BarcodePlugin(ConsumeTaskPlugin):
         # No op if not a TIFF
         self.convert_from_tiff_to_pdf()
 
-        from pikepdf import PasswordError
-
         try:
             self.barcodes = scan_pdf(
                 self.pdf_file,
@@ -433,8 +433,6 @@ class BarcodePlugin(ConsumeTaskPlugin):
 
         document_paths = []
         fname: str = self.input_doc.original_file.stem
-        from pikepdf import Pdf
-
         with Pdf.open(self.pdf_file) as input_pdf:
             # Start with an empty document
             current_document: list[Page] = []
@@ -518,8 +516,6 @@ def scan_pdf(pdf_path: Path, settings: BarcodeConfig, work_dir: Path) -> list[Ba
     """
     barcodes: list[Barcode] = []
 
-    from pikepdf import Pdf
-
     with Pdf.open(pdf_path) as pdf:
         num_of_pages = len(pdf.pages)
     logger.debug(f"PDF has {num_of_pages} pages")

src/documents/bulk_edit.py

@@ -255,19 +255,13 @@ def modify_tags(
     affected_docs = list(qs.values_list("pk", flat=True))
     DocumentTagRelationship = Document.tags.through
 
-    # add with all ancestors
-    expanded_add_tags: set[int] = set()
-    add_tag_objects = Tag.objects.filter(pk__in=add_tags)
-    for t in add_tag_objects:
-        expanded_add_tags.add(int(t.id))
-        expanded_add_tags.update(int(pk) for pk in t.get_ancestors_pks())
-
-    # remove with all descendants
-    expanded_remove_tags: set[int] = set()
-    remove_tag_objects = Tag.objects.filter(pk__in=remove_tags)
-    for t in remove_tag_objects:
-        expanded_remove_tags.add(int(t.id))
-        expanded_remove_tags.update(int(pk) for pk in t.get_descendants_pks())
+    hierarchy = Tag.get_hierarchy()
+    expanded_add_tags = hierarchy.with_ancestors(
+        Tag.objects.filter(pk__in=add_tags).values_list("pk", flat=True),
+    )
+    expanded_remove_tags = hierarchy.with_descendants(
+        Tag.objects.filter(pk__in=remove_tags).values_list("pk", flat=True),
+    )
 
     with transaction.atomic():
         if expanded_remove_tags:

src/documents/converters.py

@@ -1,5 +1,6 @@
 from pathlib import Path
 
+import img2pdf
 from PIL import Image
 
 from documents.utils import copy_basic_file_stats
@@ -16,8 +17,6 @@ def convert_from_tiff_to_pdf(tiff_path: Path, target_directory: Path) -> Path:
 
     Returns the path of the PDF created.
     """
-    import img2pdf
-
     # override pixel setting if needed
     maybe_override_pixel_limit()
 

src/documents/double_sided.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Final
 
 from django.conf import settings
+from pikepdf import Pdf
 
 from documents.consumer import ConsumerError
 from documents.converters import convert_from_tiff_to_pdf
@@ -84,8 +85,6 @@ class CollatePlugin(NoCleanupPluginMixin, NoSetupPluginMixin, ConsumeTaskPlugin)
                 valid_staging_exists = True
 
         if valid_staging_exists:
-            from pikepdf import Pdf
-
             try:
                 # Collate pages from second PDF in reverse order
                 with Pdf.open(staging) as pdf1, Pdf.open(pdf_file) as pdf2:

src/documents/filters.py

@@ -11,6 +11,7 @@ from decimal import InvalidOperation
 from typing import TYPE_CHECKING
 from typing import Any
 
+import dateparser
 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
 from django.db.models import Case
@@ -349,8 +350,6 @@ class DateQueryField(serializers.DateField):
             if not isinstance(value, str):
                 raise
 
-        import dateparser
-
         try:
             parsed = dateparser.parse(
                 value,

src/documents/management/commands/document_importer.py

@@ -108,6 +108,24 @@ def _deserialize_record(
         ) from e
 
     for field_name, field_value in record.get("fields", {}).items():
+        # Older exports include django-treenode's derived bookkeeping. The
+        # parent FK is authoritative; accept only these known removed fields.
+        if Model is Tag and field_name in {
+            "tn_ancestors_count",
+            "tn_ancestors_pks",
+            "tn_children_count",
+            "tn_children_pks",
+            "tn_depth",
+            "tn_descendants_count",
+            "tn_descendants_pks",
+            "tn_index",
+            "tn_level",
+            "tn_order",
+            "tn_priority",
+            "tn_siblings_count",
+            "tn_siblings_pks",
+        }:
+            continue
         field = Model._meta.get_field(field_name)
         remote = field.remote_field
 

src/documents/migrations/0028_replace_tag_tree_fields.py

@@ -0,0 +1,64 @@
+# Generated by Django 5.2.17 on 2026-10-28 22:54
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("documents", "0027_documentbarcode"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_ancestors_count",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_ancestors_pks",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_children_count",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_children_pks",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_depth",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_descendants_count",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_descendants_pks",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_index",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_level",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_order",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_priority",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_siblings_count",
+        ),
+        migrations.RemoveField(
+            model_name="tag",
+            name="tn_siblings_pks",
+        ),
+    ]

src/documents/models.py

@@ -14,7 +14,6 @@ from django.db import models
 from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
 from multiselectfield import MultiSelectField
-from treenode.models import TreeNodeModel
 
 if settings.AUDIT_LOG_ENABLED:
     from auditlog.registry import auditlog
@@ -100,7 +99,17 @@ class Correspondent(MatchingModel):
         verbose_name_plural = _("correspondents")
 
 
-class Tag(MatchingModel, TreeNodeModel):
+class Tag(MatchingModel):
+    # Keep the existing column and reverse relation during the transition.
+    tn_parent = models.ForeignKey(
+        "self",
+        blank=True,
+        null=True,
+        on_delete=models.CASCADE,
+        related_name="tn_children",
+        verbose_name=_("Parent"),
+    )
+
     color = models.CharField(_("color"), max_length=7, default="#a6cee3")
     # Maximum allowed nesting depth for tags (root = 1, max depth = 5)
     MAX_NESTING_DEPTH: Final[int] = 5
@@ -114,27 +123,51 @@ class Tag(MatchingModel, TreeNodeModel):
         ),
     )
 
-    class Meta(MatchingModel.Meta, TreeNodeModel.Meta):
+    class Meta(MatchingModel.Meta):
         verbose_name = _("tag")
         verbose_name_plural = _("tags")
 
+    @classmethod
+    def get_hierarchy(cls):
+        from documents.tag_hierarchy import TagHierarchy
+
+        return TagHierarchy(cls.objects.values_list("pk", "tn_parent_id"))
+
+    @property
+    def parent_pk(self):
+        return self.tn_parent_id
+
+    def get_parent(self):
+        return self.tn_parent
+
+    def get_ancestors_pks(self):
+        return self.get_hierarchy().ancestors(self.tn_parent_id)
+
+    def get_ancestors(self):
+        ids = self.get_ancestors_pks()
+        tags = self.__class__.objects.in_bulk(ids)
+        return [tags[pk] for pk in ids]
+
+    def get_descendants_pks(self):
+        return self.get_hierarchy().descendants([self.pk])
+
+    def get_descendants(self):
+        return self.__class__.objects.filter(pk__in=self.get_descendants_pks())
+
+    def get_children_queryset(self):
+        return self.__class__.objects.filter(tn_parent_id=self.pk)
+
     def clean(self) -> None:
-        # Prevent self-parenting and assigning a descendant as parent
-        parent = self.get_parent()
-        if parent == self:
-            raise ValidationError({"parent": _("Cannot set itself as parent.")})
-        if parent and self.pk is not None and self.is_ancestor_of(parent):
-            raise ValidationError({"parent": _("Cannot set parent to a descendant.")})
-
-        # Enforce maximum nesting depth
-        new_parent_depth = 0
-        if parent:
-            new_parent_depth = parent.get_ancestors_count() + 1
-
-        height = 0 if self.pk is None else self.get_depth()
-        deepest_new_depth = (new_parent_depth + 1) + height
-        if deepest_new_depth > self.MAX_NESTING_DEPTH:
-            raise ValidationError({"parent": _("Maximum nesting depth exceeded.")})
+        hierarchy = self.get_hierarchy()
+        if self.pk is not None and self.tn_parent_id == self.pk:
+            raise ValidationError({"tn_parent": _("Cannot set itself as parent.")})
+        ancestors = hierarchy.ancestors(self.tn_parent_id)
+        if self.pk is not None and self.pk in ancestors:
+            raise ValidationError(
+                {"tn_parent": _("Cannot set parent to a descendant.")},
+            )
+        if len(ancestors) + 1 + hierarchy.height(self.pk) > self.MAX_NESTING_DEPTH:
+            raise ValidationError({"tn_parent": _("Maximum nesting depth exceeded.")})
 
         return super().clean()
 
@@ -539,10 +572,7 @@ class Document(SoftDeleteModel, ModelWithOwner):  # type: ignore[django-manager-
         return self.created
 
     def add_nested_tags(self, tags) -> None:
-        tag_ids = set()
-        for tag in tags:
-            tag_ids.add(tag.id)
-            tag_ids.update(tag.get_ancestors_pks())
+        tag_ids = Tag.get_hierarchy().with_ancestors(tag.pk for tag in tags)
 
         tags_to_add = self.tags.model.objects.filter(id__in=tag_ids)
         self.tags.add(*tags_to_add)

src/documents/pdf_ops.py

@@ -14,6 +14,8 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 from typing import NamedTuple
 
+import pikepdf
+
 if TYPE_CHECKING:
     from collections.abc import Callable
     from collections.abc import Iterable
@@ -41,8 +43,6 @@ def rotate_pdf(src: Path, dst: Path, degrees: int) -> None:
     Rotate every page relatively on the opened document, not a rebuild, so Info,
     XMP and outlines are kept. ``src`` is not modified.
     """
-    import pikepdf
-
     with pikepdf.open(src) as pdf:
         for page in pdf.pages:
             page.rotate(degrees, relative=True)
@@ -58,8 +58,6 @@ def remove_pages(src: Path, dst: Path, pages: Iterable[int]) -> None:
     Duplicates are ignored. Pages are removed highest first so earlier removals
     never shift the index of later ones.
     """
-    import pikepdf
-
     unique = sorted(set(pages))
     _require_positive(unique)
     with pikepdf.open(src) as pdf:
@@ -83,8 +81,6 @@ def build_pdfs(
     (Info, XMP, outlines) is not carried over. Returns the written paths in output
     order.
     """
-    import pikepdf
-
     for specs, _ in outputs:
         _require_positive(spec.page for spec in specs)
 
@@ -144,8 +140,6 @@ def needs_decrypt(src: Path) -> bool:
     True if ``src`` is encrypted. A PDF that needs a password to open at all
     counts as encrypted.
     """
-    import pikepdf
-
     try:
         with pikepdf.open(src) as pdf:
             return bool(pdf.is_encrypted)
@@ -160,8 +154,6 @@ def decrypt_pdf(src: Path, make_dst: Callable[[], Path], password: str) -> Path:
     ``make_dst`` is only called once the password has been accepted, so a wrong
     password never leaves a destination behind.
     """
-    import pikepdf
-
     with pikepdf.open(src, password=password) as pdf:
         pdf.remove_unreferenced_resources()
         dst = make_dst()
@@ -178,8 +170,6 @@ class PdfMerger:
     """
 
     def __init__(self) -> None:
-        import pikepdf
-
         self._pdf = pikepdf.new()
         self._version: str = self._pdf.pdf_version
 
@@ -195,8 +185,6 @@ class PdfMerger:
         self._pdf.close()
 
     def add(self, path: Path) -> None:
-        import pikepdf
-
         with pikepdf.open(str(path)) as pdf:
             self._version = max(self._version, pdf.pdf_version)
             self._pdf.pages.extend(pdf.pages)

src/documents/plugins/date_parsing/base.py

@@ -7,6 +7,8 @@ from dataclasses import dataclass
 from types import TracebackType
 from typing import Self
 
+import dateparser
+
 logger = logging.getLogger(__name__)
 
 
@@ -78,8 +80,6 @@ class DateParserPluginBase(ABC):
 
         Uses configuration from `self.config`.
         """
-        import dateparser
-
         try:
             return dateparser.parse(
                 date_string,

src/documents/serialisers.py

@@ -589,7 +589,7 @@ class TagSerializer(MatchingModelSerializer, OwnedObjectSerializer):
 
     text_color = serializers.SerializerMethodField()
 
-    # map to treenode's tn_parent
+    # Preserve the public API parent field.
     parent = serializers.PrimaryKeyRelatedField(
         queryset=Tag.objects.all(),
         allow_null=True,
@@ -692,7 +692,9 @@ class TagSerializer(MatchingModelSerializer, OwnedObjectSerializer):
                 self.instance.clean()
             except ValidationError as e:
                 logger.debug("Tag parent validation failed: %s", e)
-                raise e
+                raise serializers.ValidationError(
+                    {"parent": e.message_dict["tn_parent"]},
+                ) from e
             finally:
                 self.instance.tn_parent = original_parent
         else:
@@ -702,7 +704,9 @@ class TagSerializer(MatchingModelSerializer, OwnedObjectSerializer):
                 temp.clean()
             except ValidationError as e:
                 logger.debug("Tag parent validation failed: %s", e)
-                raise e
+                raise serializers.ValidationError(
+                    {"parent": e.message_dict["tn_parent"]},
+                ) from e
 
         return super().validate(attrs)
 
@@ -1198,61 +1202,35 @@ class DocumentSerializer(
                             doc_id,
                         )
         if "tags" in validated_data:
-            # Respect tag hierarchy on updates:
-            # - Adding a child adds its ancestors
-            # - Removing a parent removes all its descendants
-            prev_tags = set(instance.tags.all())
-            requested_tags = set(validated_data["tags"])
+            hierarchy = Tag.get_hierarchy()
+            previous_ids = set(instance.tags.values_list("pk", flat=True))
+            requested_ids = {tag.pk for tag in validated_data["tags"]}
+            required_ids = hierarchy.with_ancestors(requested_ids - previous_ids)
+            blocked_ids = hierarchy.with_descendants(previous_ids - requested_ids)
+            blocked_ids.difference_update(required_ids)
+            final_ids = hierarchy.with_ancestors(requested_ids) - blocked_ids
+            validated_data["tags"] = list(Tag.objects.filter(pk__in=final_ids))
 
-            # Tags newly added in this update and the ancestors they require
-            added_tags = requested_tags - prev_tags
-            required_by_add_tags = set(added_tags)
-            for t in added_tags:
-                required_by_add_tags.update(t.get_ancestors())
-
-            # Tags being removed in this update and all descendants, except
-            # those required by a tag that is being added in this same update
-            removed_tags = prev_tags - requested_tags
-            blocked_tags = set(removed_tags)
-            for t in removed_tags:
-                blocked_tags.update(t.get_descendants())
-            blocked_tags.difference_update(required_by_add_tags)
-
-            # Add all parent tags
-            final_tags = set(requested_tags)
-            for t in requested_tags:
-                final_tags.update(t.get_ancestors())
-
-            # Drop removed parents and their descendants
-            final_tags.difference_update(blocked_tags)
-
-            validated_data["tags"] = list(final_tags)
         if validated_data.get("remove_inbox_tags"):
-            current_tag_ids = {t.pk for t in instance.tags.all()}
+            hierarchy = Tag.get_hierarchy()
             tags = (
                 validated_data["tags"]
                 if "tags" in validated_data
                 else list(instance.tags.all())
             )
-
-            # Tags newly added in this update, plus their ancestors, are kept
-            keep_ids: set[int] = set()
-            for tag in tags:
-                if tag.pk not in current_tag_ids:
-                    keep_ids.add(tag.pk)
-                    keep_ids.update(int(pk) for pk in tag.get_ancestors_pks())
-
-            # Remove inbox tags and their descendants, except those being kept
-            remove_ids: set[int] = set()
-            for inbox_tag in (
+            current_ids = set(instance.tags.values_list("pk", flat=True))
+            keep_ids = hierarchy.with_ancestors(
+                tag.pk for tag in tags if tag.pk not in current_ids
+            )
+            inbox_ids = (
                 Tag.objects.filter(is_inbox_tag=True)
-                .exclude(pk__in=keep_ids)
-                .only("pk", "tn_descendants_pks")
-            ):
-                remove_ids.add(inbox_tag.pk)
-                remove_ids.update(int(pk) for pk in inbox_tag.get_descendants_pks())
-
-            validated_data["tags"] = [t for t in tags if t.pk not in remove_ids]
+                .exclude(
+                    pk__in=keep_ids,
+                )
+                .values_list("pk", flat=True)
+            )
+            remove_ids = hierarchy.with_descendants(inbox_ids) - keep_ids
+            validated_data["tags"] = [tag for tag in tags if tag.pk not in remove_ids]
 
         if settings.AUDIT_LOG_ENABLED:
             with set_actor(self.user):

src/documents/tag_hierarchy.py

@@ -0,0 +1,61 @@
+"""An operation-local snapshot of tag edges, with no persistent derived fields.
+
+Never cache this globally: tasks, bulk updates and other processes can change
+parents. Callers traversing multiple tags should share one snapshot.
+"""
+
+from collections import defaultdict
+from collections.abc import Iterable
+
+
+class TagHierarchy:
+    def __init__(self, edges: Iterable[tuple[int, int | None]]) -> None:
+        self.parents = dict(edges)
+        self.children: dict[int | None, list[int]] = defaultdict(list)
+        for pk, parent in self.parents.items():
+            self.children[parent].append(pk)
+
+    def ancestors(self, parent_id: int | None) -> list[int]:
+        result = []
+        seen = set()
+        while parent_id is not None and parent_id not in seen:
+            seen.add(parent_id)
+            result.append(parent_id)
+            parent_id = self.parents.get(parent_id)
+        return result[::-1]
+
+    def with_ancestors(self, roots: Iterable[int]) -> set[int]:
+        result = set(roots)
+        for pk in list(result):
+            result.update(self.ancestors(self.parents.get(pk)))
+        return result
+
+    def with_descendants(self, roots: Iterable[int]) -> set[int]:
+        roots = set(roots)
+        return roots | self.descendants(roots)
+
+    def descendants(self, roots: Iterable[int]) -> set[int]:
+        roots = {pk for pk in roots if pk is not None}
+        seen = set(roots)
+        pending = list(roots)
+        while pending:
+            for child in self.children.get(pending.pop(), ()):
+                if child not in seen:
+                    seen.add(child)
+                    pending.append(child)
+        return seen - roots
+
+    def height(self, pk: int | None) -> int:
+        if pk is None:
+            return 0
+        seen = {pk}
+        pending = [(pk, 0)]
+        height = 0
+        while pending:
+            parent, depth = pending.pop()
+            height = max(height, depth)
+            for child in self.children.get(parent, ()):
+                if child not in seen:
+                    seen.add(child)
+                    pending.append((child, depth + 1))
+        return height

src/documents/tasks.py

@@ -76,6 +76,9 @@ from paperless.logging import consume_task_id
 from paperless.parsers import ParserContext
 from paperless.parsers.registry import get_parser_registry
 from paperless_ai.exceptions import LLMTimeoutError
+from paperless_ai.indexing import llm_index_add_or_update_document
+from paperless_ai.indexing import llm_index_remove_document
+from paperless_ai.indexing import update_llm_index
 
 if settings.AUDIT_LOG_ENABLED:
     from auditlog.models import LogEntry
@@ -336,8 +339,6 @@ def bulk_update_documents(document_ids) -> None:
 
     ai_config = AIConfig()
     if ai_config.llm_index_enabled:
-        from paperless_ai.indexing import update_llm_index
-
         update_llm_index(
             rebuild=False,
             document_ids=document_ids,
@@ -498,8 +499,6 @@ def update_document_content_maybe_archive_file(
 
             ai_config = AIConfig()
             if ai_config.llm_index_enabled:
-                from paperless_ai.indexing import llm_index_add_or_update_document
-
                 llm_index_add_or_update_document(document)
 
             clear_document_caches(document.pk)
@@ -801,15 +800,11 @@ def apply_ai_suggestions(self, action_id: int, document_id: int) -> None:
 
 @shared_task
 def update_document_in_llm_index(document) -> None:
-    from paperless_ai.indexing import llm_index_add_or_update_document
-
     llm_index_add_or_update_document(document)
 
 
 @shared_task
 def remove_document_from_llm_index(document) -> None:
-    from paperless_ai.indexing import llm_index_remove_document
-
     llm_index_remove_document(document)
 
 

src/documents/tests/date_parsing/test_date_parsing.py

@@ -71,7 +71,7 @@ class TestParseString:
         ):
             # We still need to mock dateparser.parse to force the exception
             mocker.patch(
-                "dateparser.parse",
+                "documents.plugins.date_parsing.base.dateparser.parse",
                 side_effect=ValueError(
                     "Parsing error: 01/01/2024",
                 ),
@@ -260,7 +260,7 @@ class TestRegexDateParser:
         parser = RegexDateParserPlugin(base_config)
 
         # Patch the dateparser.parse
-        target = "dateparser.parse"
+        target = "documents.plugins.date_parsing.base.dateparser.parse"
 
         def fake_parse(
             date_string: str,
@@ -335,7 +335,7 @@ class TestRegexDateParser:
         )
         parser = RegexDateParserPlugin(cfg)
 
-        target = "dateparser.parse"
+        target = "documents.plugins.date_parsing.base.dateparser.parse"
 
         def fake_parse(
             date_string: str,
@@ -400,7 +400,7 @@ class TestRegexDateParser:
         parser = RegexDateParserPlugin(cfg)
 
         # Patch the module's dateparser.parse so we can inspect calls
-        target = "dateparser.parse"
+        target = "documents.plugins.date_parsing.base.dateparser.parse"
 
         def fake_parse(
             date_string: str,

src/documents/tests/test_api_app_config.py

@@ -1070,7 +1070,7 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
 
         with (
             patch("documents.tasks.llmindex_index.apply_async") as mock_update,
-            patch("paperless_ai.indexing.llm_index_exists") as mock_exists,
+            patch("paperless.views.llm_index_exists") as mock_exists,
         ):
             mock_exists.return_value = False
             self.client.patch(
@@ -1095,7 +1095,7 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
 
         with (
             patch("documents.tasks.llmindex_index.apply_async") as mock_update,
-            patch("paperless_ai.indexing.llm_index_exists", return_value=False),
+            patch("paperless.views.llm_index_exists", return_value=False),
         ):
             self.client.patch(
                 f"{self.ENDPOINT}1/",
@@ -1115,7 +1115,7 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
 
         with (
             patch("documents.tasks.llmindex_index.apply_async") as mock_update,
-            patch("paperless_ai.indexing.llm_index_exists") as mock_exists,
+            patch("paperless.views.llm_index_exists") as mock_exists,
         ):
             mock_exists.return_value = True
             self.client.patch(
@@ -1136,7 +1136,7 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
 
         with (
             patch("documents.tasks.llmindex_index.apply_async") as mock_update,
-            patch("paperless_ai.indexing.llm_index_exists") as mock_exists,
+            patch("paperless.views.llm_index_exists") as mock_exists,
         ):
             mock_exists.return_value = True
             self.client.patch(
@@ -1174,7 +1174,7 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
 
         with (
             patch("documents.tasks.llmindex_index.apply_async") as mock_update,
-            patch("paperless_ai.indexing.llm_index_exists") as mock_exists,
+            patch("paperless.views.llm_index_exists") as mock_exists,
         ):
             mock_exists.return_value = True
             self.client.patch(

src/documents/tests/test_api_chat.py

@@ -61,7 +61,7 @@ class TestChatStreamingViewInputValidation(APITestCase):
                 return_value=self._mock_ai_enabled(),
             ),
             mock.patch(
-                "paperless_ai.chat.stream_chat_with_documents",
+                "documents.views.stream_chat_with_documents",
                 return_value=iter(chunks),
             ),
         ):
@@ -104,7 +104,7 @@ class TestChatStreamingViewUnrestrictedFlag:
         """
         mocker.patch("documents.views.AIConfig").return_value.ai_enabled = True
         return mocker.patch(
-            "paperless_ai.chat.stream_chat_with_documents",
+            "documents.views.stream_chat_with_documents",
             return_value=iter(()),
         )
 

src/documents/tests/test_api_document_versions.py

@@ -1110,7 +1110,7 @@ class TestVersionActionPermissions(DirectoriesMixin, APITestCase):
             self.assertEqual(response.status_code, 403)
             with (
                 mock.patch("documents.views.AIConfig") as ai_config,
-                mock.patch("paperless_ai.chat.stream_chat_with_documents") as chat,
+                mock.patch("documents.views.stream_chat_with_documents") as chat,
             ):
                 ai_config.return_value.ai_enabled = True
                 response = self.client.post(

src/documents/tests/test_api_documents.py

@@ -2686,7 +2686,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
         response = self.client.get("/api/documents/34676/suggestions/")
         self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
 
-    @mock.patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @mock.patch("documents.views.get_ai_document_classification")
     @override_settings(AI_ENABLED=True)
     def test_suggestions_still_uses_classifier_when_ai_enabled(
         self,

src/documents/tests/test_permission_filtering_security.py

@@ -572,7 +572,7 @@ class TestAiChatAllDocumentsPermissionBoundary:
     ENDPOINT = "/api/documents/chat/"
 
     @override_settings(AI_ENABLED=True)
-    @patch("paperless_ai.chat.stream_chat_with_documents")
+    @patch("documents.views.stream_chat_with_documents")
     def test_chat_all_documents_excludes_unshared_document(self, mock_stream_chat):
         mock_stream_chat.return_value = iter([b"data"])
 

src/documents/tests/test_tag_adjacency.py

@@ -0,0 +1,104 @@
+from django.core.exceptions import FieldDoesNotExist
+from django.db import connection
+from django.test import TestCase
+from django.test.utils import CaptureQueriesContext
+
+from documents.management.commands.document_importer import _deserialize_record
+from documents.models import Tag
+from documents.tag_hierarchy import TagHierarchy
+from paperless_testing.migrations import TestMigrations
+
+
+class TestTagAdjacency(TestCase):
+    def test_held_instance_uses_current_parent_edges(self):
+        first = Tag.objects.create(name="First")
+        second = Tag.objects.create(name="Second")
+        child = Tag.objects.create(name="Child", tn_parent=first)
+        Tag.objects.filter(pk=child.pk).update(tn_parent=second)
+        assert first.get_descendants_pks() == set()
+        assert second.get_descendants_pks() == {child.pk}
+
+    def test_queryset_delete_preserves_cascade(self):
+        root = Tag.objects.create(name="Root")
+        child = Tag.objects.create(name="Child", tn_parent=root)
+        Tag.objects.create(name="Grandchild", tn_parent=child)
+        survivor = Tag.objects.create(name="Other root")
+        Tag.objects.filter(pk=root.pk).delete()
+        assert list(Tag.objects.values_list("pk", flat=True)) == [survivor.pk]
+
+    def test_flat_writes_do_not_update_other_tags(self):
+        Tag.objects.bulk_create([Tag(name=f"Tag {i}") for i in range(100)])
+        with CaptureQueriesContext(connection) as queries:
+            new = Tag.objects.create(name="New")
+        assert not any(q["sql"].startswith("UPDATE") for q in queries)
+        with CaptureQueriesContext(connection) as queries:
+            new.name = "Renamed"
+            new.save()
+        tag_updates = [
+            q["sql"] for q in queries if q["sql"].startswith('UPDATE "documents_tag"')
+        ]
+        assert len(tag_updates) == 1
+        assert 'WHERE "documents_tag"."id" =' in tag_updates[0]
+
+    def test_batch_snapshot_is_one_query_and_includes_overlapping_roots(self):
+        root = Tag.objects.create(name="Root")
+        child = Tag.objects.create(name="Child", tn_parent=root)
+        leaf = Tag.objects.create(name="Leaf", tn_parent=child)
+        with self.assertNumQueries(1):
+            hierarchy = Tag.get_hierarchy()
+            assert hierarchy.with_ancestors([leaf.pk]) == {root.pk, child.pk, leaf.pk}
+            assert hierarchy.with_descendants([root.pk, child.pk]) == {
+                root.pk,
+                child.pk,
+                leaf.pk,
+            }
+        assert hierarchy.height(None) == 0
+
+    def test_legacy_export_fields_are_ignored_but_parent_is_preserved(self):
+        model, tag, m2m = _deserialize_record(
+            {
+                "model": "documents.tag",
+                "pk": 2,
+                "fields": {
+                    "name": "Child",
+                    "tn_parent": 1,
+                    "tn_order": 3,
+                    "tn_siblings_pks": "4,5",
+                    "tn_descendants_pks": "6",
+                },
+            },
+        )
+        assert model is Tag
+        assert tag.tn_parent_id == 1
+        assert tag.name == "Child"
+        assert not m2m
+        with self.assertRaises(FieldDoesNotExist):
+            _deserialize_record(
+                {"model": "documents.tag", "pk": 3, "fields": {"tn_typo": "bad"}},
+            )
+
+    def test_malformed_cycles_terminate(self):
+        hierarchy = TagHierarchy([(1, 2), (2, 1)])
+        assert hierarchy.with_descendants([1]) == {1, 2}
+        assert set(hierarchy.ancestors(2)) == {1, 2}
+
+
+class TestTagAdjacencyMigration(TestMigrations):
+    migrate_from = "0027_documentbarcode"
+    migrate_to = "0028_replace_tag_tree_fields"
+
+    def setUpBeforeMigration(self, apps):
+        tag = apps.get_model("documents", "Tag")
+        root = tag.objects.create(name="Root")
+        child = tag.objects.create(name="Child", tn_parent=root)
+        self.edges = [(root.pk, None), (child.pk, root.pk)]
+
+    def test_parent_edges_survive(self):
+        tag = self.apps.get_model("documents", "Tag")
+        assert (
+            list(tag.objects.order_by("pk").values_list("pk", "tn_parent_id"))
+            == self.edges
+        )
+        assert {
+            field.name for field in tag._meta.fields if field.name.startswith("tn_")
+        } == {"tn_parent"}

src/documents/tests/test_tasks.py

@@ -322,7 +322,7 @@ class TestUpdateContent(DirectoriesMixin, TestCase):
         )
 
     @override_settings(AI_ENABLED=True, LLM_EMBEDDING_BACKEND="huggingface")
-    @mock.patch("paperless_ai.indexing.llm_index_add_or_update_document")
+    @mock.patch("documents.tasks.llm_index_add_or_update_document")
     @mock.patch("documents.search.get_backend")
     def test_update_content_version_updates_llm_index(
         self,
@@ -450,7 +450,7 @@ class TestAIIndex(DirectoriesMixin, TestCase):
             checksum="wow",
         )
         with mock.patch(
-            "paperless_ai.indexing.llm_index_add_or_update_document",
+            "documents.tasks.llm_index_add_or_update_document",
         ) as llm_index_add_or_update_document:
             tasks.update_document_in_llm_index(doc)
             llm_index_add_or_update_document.assert_called_once_with(doc)
@@ -470,7 +470,7 @@ class TestAIIndex(DirectoriesMixin, TestCase):
             checksum="wow",
         )
         with mock.patch(
-            "paperless_ai.indexing.llm_index_remove_document",
+            "documents.tasks.llm_index_remove_document",
         ) as llm_index_remove_document:
             tasks.remove_document_from_llm_index(doc)
             llm_index_remove_document.assert_called_once_with(doc)
@@ -495,7 +495,7 @@ class TestAIIndex(DirectoriesMixin, TestCase):
                 "documents.tasks.update_document_in_llm_index",
             ) as update_document_in_llm_index,
             mock.patch(
-                "paperless_ai.indexing.update_llm_index",
+                "documents.tasks.update_llm_index",
             ) as update_llm_index,
         ):
             doc_ids = [doc.pk for doc in docs]

src/documents/tests/test_views.py

@@ -474,7 +474,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
         self.assertEqual(response.json()["tags"], [])
         self.assertEqual(response.json()["suggested_tags"], [])
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -524,7 +524,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             None,
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -562,7 +562,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             "KI Title",
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -601,7 +601,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             "Titre IA",
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -637,7 +637,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             ),
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -709,7 +709,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             ),
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="openai-like",
@@ -738,7 +738,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             get_llm_suggestion_cache(self.document.pk, backend="openai-like"),
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="openai-like",
@@ -765,7 +765,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             get_llm_suggestion_cache(self.document.pk, backend="openai-like"),
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="openai-like",
@@ -797,7 +797,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
             get_llm_suggestion_cache(self.document.pk, backend="openai-like"),
         )
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -835,7 +835,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
         self.assertEqual(response.json()["tags"], [self.tag1.pk])
         self.assertEqual(response.json()["suggested_tags"], ["Follow-up"])
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -874,7 +874,7 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
         self.assertEqual(response.json()["tags"], [self.tag1.pk])
         self.assertEqual(response.json()["suggested_tags"], [])
 
-    @patch("paperless_ai.ai_classifier.get_ai_document_classification")
+    @patch("documents.views.get_ai_document_classification")
     @override_settings(
         AI_ENABLED=True,
         LLM_BACKEND="mock_backend",
@@ -996,7 +996,7 @@ class TestAIChatStreamingView(DirectoriesMixin, TestCase):
         self.assertEqual(response.status_code, 400)
         self.assertIn(b"AI is required for this feature", response.content)
 
-    @patch("paperless_ai.chat.stream_chat_with_documents")
+    @patch("documents.views.stream_chat_with_documents")
     @patch("documents.views.permitted_document_ids")
     @override_settings(AI_ENABLED=True)
     def test_post_no_document_id(self, mock_permitted_ids, mock_stream_chat) -> None:
@@ -1016,7 +1016,7 @@ class TestAIChatStreamingView(DirectoriesMixin, TestCase):
         self.assertEqual(list(call_kwargs["documents"]), [self.document])
         self.assertIsNone(call_kwargs["output_language"])
 
-    @patch("paperless_ai.chat.stream_chat_with_documents")
+    @patch("documents.views.stream_chat_with_documents")
     @patch("documents.views.permitted_document_ids")
     @override_settings(AI_ENABLED=True)
     def test_post_uses_user_display_language(
@@ -1042,7 +1042,7 @@ class TestAIChatStreamingView(DirectoriesMixin, TestCase):
         self.assertEqual(list(call_kwargs["documents"]), [self.document])
         self.assertEqual(call_kwargs["output_language"], "de-de")
 
-    @patch("paperless_ai.chat.stream_chat_with_documents")
+    @patch("documents.views.stream_chat_with_documents")
     @override_settings(AI_ENABLED=True)
     def test_post_with_document_id(self, mock_stream_chat) -> None:
         self.grant_view_document_permission()
@@ -1079,7 +1079,7 @@ class TestAIChatStreamingView(DirectoriesMixin, TestCase):
         self.assertEqual(response.status_code, 403)
         self.assertIn(b"Insufficient permissions", response.content)
 
-    @patch("paperless_ai.chat.stream_chat_with_documents")
+    @patch("documents.views.stream_chat_with_documents")
     @override_settings(AI_ENABLED=True)
     def test_post_no_document_id_requires_view_document_permission(
         self,
@@ -1093,7 +1093,7 @@ class TestAIChatStreamingView(DirectoriesMixin, TestCase):
         self.assertEqual(response.status_code, 403)
         mock_stream_chat.assert_not_called()
 
-    @patch("paperless_ai.chat.stream_chat_with_documents")
+    @patch("documents.views.stream_chat_with_documents")
     @override_settings(AI_ENABLED=True)
     def test_post_with_document_id_requires_view_document_permission(
         self,

src/documents/views.py

@@ -250,8 +250,20 @@ from paperless.parsers.remote import RemoteEngineConfig
 from paperless.serialisers import GroupSerializer
 from paperless.serialisers import UserSerializer
 from paperless.views import StandardPagination
+from paperless_ai.ai_classifier import get_ai_document_classification
+from paperless_ai.ai_classifier import get_llm_output_language
+from paperless_ai.chat import stream_chat_with_documents
 from paperless_ai.exceptions import LLMProviderError
 from paperless_ai.exceptions import LLMTimeoutError
+from paperless_ai.matching import extract_unmatched_names
+from paperless_ai.matching import match_correspondents_by_name
+from paperless_ai.matching import match_document_types_by_name
+from paperless_ai.matching import match_storage_paths_by_name
+from paperless_ai.matching import match_tags_by_name
+from paperless_ai.matching import resolve_correspondent_ids
+from paperless_ai.matching import resolve_document_type_ids
+from paperless_ai.matching import resolve_storage_path_ids
+from paperless_ai.matching import resolve_tag_ids
 from paperless_mail.models import MailAccount
 from paperless_mail.models import MailRule
 from paperless_mail.oauth import PaperlessMailOAuth2Manager
@@ -615,7 +627,7 @@ class TagViewSet(PermissionsAwareDocumentCountMixin, ModelViewSet[Tag]):
         queryset = queryset.order_by(*ordering)
 
         all_tags = list(queryset)
-        descendant_pks = {pk for tag in all_tags for pk in tag.get_descendants_pks()}
+        descendant_pks = Tag.get_hierarchy().descendants(t.pk for t in all_tags)
 
         if descendant_pks:
             user = getattr(getattr(self, "request", None), "user", None)
@@ -1601,18 +1613,6 @@ class DocumentViewSet(
         if not ai_config.ai_enabled:
             return HttpResponseBadRequest("AI is required for this feature")
 
-        from paperless_ai.ai_classifier import get_ai_document_classification
-        from paperless_ai.ai_classifier import get_llm_output_language
-        from paperless_ai.matching import extract_unmatched_names
-        from paperless_ai.matching import match_correspondents_by_name
-        from paperless_ai.matching import match_document_types_by_name
-        from paperless_ai.matching import match_storage_paths_by_name
-        from paperless_ai.matching import match_tags_by_name
-        from paperless_ai.matching import resolve_correspondent_ids
-        from paperless_ai.matching import resolve_document_type_ids
-        from paperless_ai.matching import resolve_storage_path_ids
-        from paperless_ai.matching import resolve_tag_ids
-
         output_language = get_llm_output_language(
             ai_config=ai_config,
             user=request.user,
@@ -2446,9 +2446,6 @@ class ChatStreamingView(GenericAPIView[Any]):
             )
             unrestricted = user_is_unrestricted(request.user)
 
-        from paperless_ai.ai_classifier import get_llm_output_language
-        from paperless_ai.chat import stream_chat_with_documents
-
         output_language = get_llm_output_language(
             ai_config=ai_config,
             user=request.user,
@@ -5063,12 +5060,7 @@ class BulkEditObjectsView(PassUserMixin):
             if object_type == "tags":
                 editable_ids = set(user_permitted_objects.values_list("pk", flat=True))
                 all_ids = set(objs.values_list("pk", flat=True))
-                for tag in objs:
-                    all_ids.update(
-                        descendant.pk
-                        for descendant in tag.get_descendants()
-                        if descendant.pk in editable_ids
-                    )
+                all_ids.update(Tag.get_hierarchy().descendants(all_ids) & editable_ids)
                 objs = object_class.objects.filter(pk__in=all_ids)
             objs = objs.select_related("owner")
             object_ids = list(objs.values_list("pk", flat=True))

src/documents/workflows/mutations.py

@@ -6,6 +6,7 @@ from guardian.shortcuts import remove_perm
 from documents.data_models import DocumentMetadataOverrides
 from documents.models import CustomFieldInstance
 from documents.models import Document
+from documents.models import Tag
 from documents.models import WorkflowAction
 from documents.permissions import PermissionsSpec
 from documents.permissions import set_permissions_for_objects
@@ -134,10 +135,9 @@ def apply_assignment_to_overrides(
     if action.has_assign_tags:
         if overrides.tag_ids is None:
             overrides.tag_ids = []
-        tag_ids_to_add: set[int] = set()
-        for tag in action.assign_tags.all():
-            tag_ids_to_add.add(tag.pk)
-            tag_ids_to_add.update(int(pk) for pk in tag.get_ancestors_pks())
+        tag_ids_to_add = Tag.get_hierarchy().with_ancestors(
+            tag.pk for tag in action.assign_tags.all()
+        )
 
         overrides.tag_ids = list(set(overrides.tag_ids) | tag_ids_to_add)
 
@@ -216,10 +216,9 @@ def apply_removal_to_document(
     if action.remove_all_tags:
         Document.objects.get(pk=document.pk).tags.clear()
     else:
-        tag_ids_to_remove: set[int] = set()
-        for tag in action.remove_tags.all():
-            tag_ids_to_remove.add(tag.pk)
-            tag_ids_to_remove.update(int(pk) for pk in tag.get_descendants_pks())
+        tag_ids_to_remove = Tag.get_hierarchy().with_descendants(
+            tag.pk for tag in action.remove_tags.all()
+        )
 
         if tag_ids_to_remove:
             Document.objects.get(pk=document.pk).tags.remove(*tag_ids_to_remove)
@@ -297,10 +296,9 @@ def apply_removal_to_overrides(
     if action.remove_all_tags:
         overrides.tag_ids = None
     elif overrides.tag_ids:
-        tag_ids_to_remove: set[int] = set()
-        for tag in action.remove_tags.all():
-            tag_ids_to_remove.add(tag.pk)
-            tag_ids_to_remove.update(int(pk) for pk in tag.get_descendants_pks())
+        tag_ids_to_remove = Tag.get_hierarchy().with_descendants(
+            tag.pk for tag in action.remove_tags.all()
+        )
 
         overrides.tag_ids = [t for t in overrides.tag_ids if t not in tag_ids_to_remove]
 

src/paperless/asgi.py

@@ -17,7 +17,7 @@ from paperless.urls import websocket_urlpatterns  # noqa: E402
 
 application = ProtocolTypeRouter(
     {
-        "http": django_asgi_app,
+        "http": get_asgi_application(),
         "websocket": AuthMiddlewareStack(URLRouter(websocket_urlpatterns)),
     },
 )

src/paperless/parsers/mail.py

@@ -36,6 +36,9 @@ from humanize import naturalsize
 from imap_tools import MailAttachment
 from imap_tools import MailMessage
 from tika_client import TikaClient
+from turbohtml.clean import Linkify
+from turbohtml.clean import linkify
+from turbohtml.migration.bleach import clean
 
 from documents.parsers import ParseError
 from documents.parsers import make_thumbnail_from_pdf
@@ -619,10 +622,6 @@ class MailDocumentParser:
 
         def clean_html(text: str) -> str:
             """Attempt to clean, escape, and linkify the given HTML string."""
-            from turbohtml.clean import Linkify
-            from turbohtml.clean import linkify
-            from turbohtml.migration.bleach import clean
-
             if isinstance(text, list):
                 text = "\n".join([str(e) for e in text])
             if not isinstance(text, str):

src/paperless/parsers/tesseract.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import functools
 import importlib.resources
 import logging
 import os
@@ -40,12 +39,9 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("paperless.parsing.tesseract")
 
-
-@functools.cache
-def _srgb_icc_data() -> bytes:
-    # Read on first use, importing ocrmypdf.data pulls in the whole ocrmypdf package
-    return importlib.resources.files("ocrmypdf.data").joinpath("sRGB.icc").read_bytes()
-
+_SRGB_ICC_DATA: Final[bytes] = (
+    importlib.resources.files("ocrmypdf.data").joinpath("sRGB.icc").read_bytes()
+)
 
 _SUPPORTED_MIME_TYPES: Final[dict[str, str]] = {
     "application/pdf": ".pdf",
@@ -407,7 +403,7 @@ class RasterisedDocumentParser:
         pdfa_path = Path(self.tempdir) / "archive.pdf"
         try:
             with pikepdf.open(plain_pdf_path) as pdf:
-                cs = pdf.make_stream(_srgb_icc_data())
+                cs = pdf.make_stream(_SRGB_ICC_DATA)
                 cs["/N"] = 3
                 output_intent = pikepdf.Dictionary(
                     Type=pikepdf.Name("/OutputIntent"),

src/paperless/settings/__init__.py

@@ -157,7 +157,6 @@ INSTALLED_APPS = [
     "allauth.headless",
     "drf_spectacular",
     "drf_spectacular_sidecar",
-    "treenode",
     *env_apps,
 ]
 

src/paperless/settings/custom.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Any
 
 from celery.schedules import crontab
+from dateparser.languages.loader import LocaleDataLoader
 
 from paperless.settings.parsers import get_choice_from_env
 from paperless.settings.parsers import get_int_from_env
@@ -351,8 +352,6 @@ def parse_dateparser_languages(languages: str | None) -> list[str]:
             )
             language_list.append("zh")
 
-    from dateparser.languages.loader import LocaleDataLoader
-
     return list(LocaleDataLoader().get_locale_map(locales=language_list))
 
 

src/paperless/tests/test_utils.py

@@ -59,10 +59,7 @@ def test_ocr_to_dateparser_languages_exception(
             raise RuntimeError("Simulated error")
 
     with caplog.at_level(logging.WARNING):
-        monkeypatch.setattr(
-            "dateparser.languages.loader.LocaleDataLoader",
-            lambda: DummyLoader(),
-        )
+        monkeypatch.setattr(utils, "LocaleDataLoader", lambda: DummyLoader())
         result = utils.ocr_to_dateparser_languages("eng+fra")
         assert result == []
         assert (

src/paperless/utils.py

@@ -1,5 +1,7 @@
 import logging
 
+from dateparser.languages.loader import LocaleDataLoader
+
 logger = logging.getLogger("paperless.utils")
 
 OCR_TO_DATEPARSER_LANGUAGES = {
@@ -123,8 +125,6 @@ def ocr_to_dateparser_languages(ocr_languages: str) -> list[str]:
     - If a language cannot be mapped or validated, it is skipped with a warning.
     - Returns a list of valid locales, or an empty list if none could be converted.
     """
-    from dateparser.languages.loader import LocaleDataLoader
-
     loader = LocaleDataLoader()
     result = []
     try:

src/paperless/validators.py

@@ -3,6 +3,7 @@ from io import BytesIO
 from django.conf import settings
 from django.core.exceptions import ValidationError
 from django.core.files.uploadedfile import UploadedFile
+from lxml import etree
 from PIL import Image
 
 ALLOWED_SVG_TAGS: set[str] = {
@@ -185,7 +186,6 @@ def reject_dangerous_svg(file: UploadedFile) -> None:
     Raises ValidationError if unsafe content is found.
     See GHSA-6p53-hqqw-8j62
     """
-    from lxml import etree
 
     try:
         parser = etree.XMLParser(resolve_entities=False)

src/paperless/views.py

@@ -49,6 +49,7 @@ from paperless.serialisers import GroupSerializer
 from paperless.serialisers import PaperlessAuthTokenSerializer
 from paperless.serialisers import ProfileSerializer
 from paperless.serialisers import UserSerializer
+from paperless_ai.indexing import llm_index_exists
 
 
 class PaperlessObtainAuthTokenView(ObtainAuthToken):
@@ -470,8 +471,6 @@ class ApplicationConfigurationViewSet(ModelViewSet[ApplicationConfiguration]):
             or old_llm_embedding_model != new_llm_embedding_model
             or old_llm_context_size != new_llm_context_size
         )
-        from paperless_ai.indexing import llm_index_exists
-
         rebuild_needed = new_ai_index_enabled and (
             not llm_index_exists() or embedding_config_changed
         )

uv.lock

@@ -1210,15 +1210,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/99/c3/305a9f7611c0dc96d2a638bc3a67bdcde5a7faa5f4669188db018b8af6fc/django_stubs_ext-6.1.1-py3-none-any.whl", hash = "sha256:64aebb7ce2c327a4a2b75207d67034e879fd7edf027c93487be69da363dc79fa", size = 10853, upload-time = "2026-09-14T08:45:51.289Z" },
 ]
 
-[[package]]
-name = "django-treenode"
-version = "0.25.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/cb/2b/09f04b44b3583a911ae4f5d0e3360a23d529704c9e9115fce2520b7d4420/django_treenode-0.25.0.tar.gz", hash = "sha256:d14d0eb3571c227ce11147210d62a8f87b568bbb30fa76a5be9b9e6d514157c3", size = 29951, upload-time = "2026-08-26T00:20:13.489Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e1/ac/2140e8c20e2a47457ec23302273527d3430bf5c09edb8940d74c0725c138/django_treenode-0.25.0-py3-none-any.whl", hash = "sha256:f47caab5440420870b6287602b3ee401ca354416d44b24ab97579be5ea658927", size = 22343, upload-time = "2026-08-26T00:20:12.078Z" },
-]
-
 [[package]]
 name = "djangorestframework"
 version = "3.18.3"
@@ -3107,7 +3098,6 @@ dependencies = [
     { name = "django-multiselectfield" },
     { name = "django-rich" },
     { name = "django-soft-delete" },
-    { name = "django-treenode" },
     { name = "djangorestframework" },
     { name = "drf-spectacular" },
     { name = "drf-spectacular-sidecar" },
@@ -3258,7 +3248,6 @@ requires-dist = [
     { name = "django-multiselectfield", specifier = "~=1.0.1" },
     { name = "django-rich", specifier = "~=2.2.0" },
     { name = "django-soft-delete", specifier = "~=1.0.18" },
-    { name = "django-treenode", specifier = ">=0.24" },
     { name = "djangorestframework", specifier = "~=3.16" },
     { name = "drf-spectacular", specifier = "~=0.30" },
     { name = "drf-spectacular-sidecar", specifier = ">=2026.7.1,<2026.10" },