Not bad catches from Copilot, if a little extra secure

feature: add Tantivy full-text fallback adapter for taxonomy candidates
This brings users without an embedding backend configured to closer parity with those who do. Reuse the search backend to locate similar documents and use them to provide the LLM with the better suggestion pool to draw from
2026-08-29 05:57:32 +00:00 · 2026-08-27 11:37:07 -07:00 · 2026-08-27 09:42:08 -07:00
55 changed files with 616 additions and 436 deletions
@@ -186,110 +186,29 @@ line-ending = "lf"
 # https://docs.astral.sh/ruff/rules/
 select = [ "E4", "E7", "E9", "F" ]
 extend-select = [
-  "ASYNC",   # https://docs.astral.sh/ruff/rules/#flake8-async-async
-  "B002",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B003",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B004",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B005",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B006",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B008",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B009",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B010",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B012",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B013",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B014",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B015",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B016",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B017",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B018",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B019",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B020",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B021",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B022",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B023",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B025",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B026",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B029",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B030",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B031",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B032",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B033",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B035",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "B039",    # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
-  "C4",      # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
-  "COM",     # https://docs.astral.sh/ruff/rules/#flake8-commas-com
-  "D419",    # https://docs.astral.sh/ruff/rules/#pydocstyle-d
-  "DJ",      # https://docs.astral.sh/ruff/rules/#flake8-django-dj
-  "DTZ",     # https://docs.astral.sh/ruff/rules/#flake8-datetimez-dtz
-  "EXE",     # https://docs.astral.sh/ruff/rules/#flake8-executable-exe
-  "FA",      # https://docs.astral.sh/ruff/rules/#flake8-future-annotations-fa
-  "FBT",     # https://docs.astral.sh/ruff/rules/#flake8-boolean-trap-fbt
-  "FLY",     # https://docs.astral.sh/ruff/rules/#flynt-fly
-  "FURB",    # https://docs.astral.sh/ruff/rules/#refurb-furb
-  "G010",    # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
-  "G101",    # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
-  "G201",    # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
-  "G202",    # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
-  "I",       # https://docs.astral.sh/ruff/rules/#isort-i
-  "ICN",     # https://docs.astral.sh/ruff/rules/#flake8-import-conventions-icn
-  "INP",     # https://docs.astral.sh/ruff/rules/#flake8-no-pep420-inp
-  "INT001",  # https://docs.astral.sh/ruff/rules/#flake8-gettext-int
-  "INT002",  # https://docs.astral.sh/ruff/rules/#flake8-gettext-int
-  "INT003",  # https://docs.astral.sh/ruff/rules/#flake8-gettext-int
-  "ISC",     # https://docs.astral.sh/ruff/rules/#flake8-implicit-str-concat-isc
-  "LOG001",  # https://docs.astral.sh/ruff/rules/#flake8-logging-log
-  "LOG002",  # https://docs.astral.sh/ruff/rules/#flake8-logging-log
-  "LOG009",  # https://docs.astral.sh/ruff/rules/#flake8-logging-log
-  "LOG014",  # https://docs.astral.sh/ruff/rules/#flake8-logging-log
-  "LOG015",  # https://docs.astral.sh/ruff/rules/#flake8-logging-log
-  "N999",    # https://docs.astral.sh/ruff/rules/#pep8-naming-n
-  "PERF101", # https://docs.astral.sh/ruff/rules/#perflint-perf
-  "PERF102", # https://docs.astral.sh/ruff/rules/#perflint-perf
-  "PERF402", # https://docs.astral.sh/ruff/rules/#perflint-perf
-  "PGH005",  # https://docs.astral.sh/ruff/rules/#pygrep-hooks-pgh
-  "PIE",     # https://docs.astral.sh/ruff/rules/#flake8-pie-pie
-  "PLC",     # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLE",     # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR0124", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR0133", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR0206", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR0402", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1704", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1708", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1711", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1716", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1722", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1730", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1733", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR1736", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLR2044", # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PLW",     # https://docs.astral.sh/ruff/rules/#pylint-pl
-  "PT010",   # https://docs.astral.sh/ruff/rules/#flake8-pytest-style-pt
-  "PT014",   # https://docs.astral.sh/ruff/rules/#flake8-pytest-style-pt
-  "PT020",   # https://docs.astral.sh/ruff/rules/#flake8-pytest-style-pt
-  "PT025",   # https://docs.astral.sh/ruff/rules/#flake8-pytest-style-pt
-  "PT026",   # https://docs.astral.sh/ruff/rules/#flake8-pytest-style-pt
-  "PT031",   # https://docs.astral.sh/ruff/rules/#flake8-pytest-style-pt
-  "PTH",     # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
-  "Q",       # https://docs.astral.sh/ruff/rules/#flake8-quotes-q
-  "RSE",     # https://docs.astral.sh/ruff/rules/#flake8-raise-rse
-  "RUF",     # https://docs.astral.sh/ruff/rules/#ruff-specific-rules-ruf
-  "S102",    # https://docs.astral.sh/ruff/rules/#flake8-bandit-s
-  "S110",    # https://docs.astral.sh/ruff/rules/#flake8-bandit-s
-  "S112",    # https://docs.astral.sh/ruff/rules/#flake8-bandit-s
-  "SIM",     # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
-  "T100",    # https://docs.astral.sh/ruff/rules/#flake8-debugger-t10
-  "T20",     # https://docs.astral.sh/ruff/rules/#flake8-print-t20
-  "TC",      # https://docs.astral.sh/ruff/rules/#flake8-type-checking-tc
-  "TID",     # https://docs.astral.sh/ruff/rules/#flake8-tidy-imports-tid
-  "TRY002",  # https://docs.astral.sh/ruff/rules/#tryceratops-try
-  "TRY004",  # https://docs.astral.sh/ruff/rules/#tryceratops-try
-  "TRY201",  # https://docs.astral.sh/ruff/rules/#tryceratops-try
-  "TRY203",  # https://docs.astral.sh/ruff/rules/#tryceratops-try
-  "TRY401",  # https://docs.astral.sh/ruff/rules/#tryceratops-try
-  "UP",      # https://docs.astral.sh/ruff/rules/#pyupgrade-up
-  "W",       # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
-  "YTT",     # https://docs.astral.sh/ruff/rules/#flake8-2020-ytt
+  "COM",  # https://docs.astral.sh/ruff/rules/#flake8-commas-com
+  "DJ",   # https://docs.astral.sh/ruff/rules/#flake8-django-dj
+  "EXE",  # https://docs.astral.sh/ruff/rules/#flake8-executable-exe
+  "FBT",  # https://docs.astral.sh/ruff/rules/#flake8-boolean-trap-fbt
+  "FLY",  # https://docs.astral.sh/ruff/rules/#flynt-fly
+  "G201", # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
+  "I",    # https://docs.astral.sh/ruff/rules/#isort-i
+  "ICN",  # https://docs.astral.sh/ruff/rules/#flake8-import-conventions-icn
+  "INP",  # https://docs.astral.sh/ruff/rules/#flake8-no-pep420-inp
+  "ISC",  # https://docs.astral.sh/ruff/rules/#flake8-implicit-str-concat-isc
+  "PIE",  # https://docs.astral.sh/ruff/rules/#flake8-pie-pie
+  "PLC",  # https://docs.astral.sh/ruff/rules/#pylint-pl
+  "PLE",  # https://docs.astral.sh/ruff/rules/#pylint-pl
+  "PTH",  # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
+  "Q",    # https://docs.astral.sh/ruff/rules/#flake8-quotes-q
+  "RSE",  # https://docs.astral.sh/ruff/rules/#flake8-raise-rse
+  "RUF",  # https://docs.astral.sh/ruff/rules/#ruff-specific-rules-ruf
+  "SIM",  # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
+  "T20",  # https://docs.astral.sh/ruff/rules/#flake8-print-t20
+  "TC",   # https://docs.astral.sh/ruff/rules/#flake8-type-checking-tc
+  "TID",  # https://docs.astral.sh/ruff/rules/#flake8-tidy-imports-tid
+  "UP",   # https://docs.astral.sh/ruff/rules/#pyupgrade-up
+  "W",    # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
 ]
 ignore = [
  "DJ001",
@@ -305,7 +224,6 @@ per-file-ignores."*/migrations/*.py" = [
 ]
 # Testing
 per-file-ignores."*/tests/*.py" = [
-  "DTZ",
  "E501",
  "SIM117",
 ]
@@ -507,8 +507,8 @@ def rotate(
            logger.info(
                f"Queued new rotated version for document {pair.root_doc.id} by {degrees} degrees",
            )
-        except Exception:
-            logger.exception(f"Error rotating document {pair.root_doc.id}")
+        except Exception as e:
+            logger.exception(f"Error rotating document {pair.root_doc.id}: {e}")

    return "OK"

@@ -554,9 +554,9 @@ def merge(
            affected_docs.append(doc.id)
            if handoff_asn is None and doc.archive_serial_number is not None:
                handoff_asn = doc.archive_serial_number
-        except Exception:
+        except Exception as e:
            logger.exception(
-                f"Error merging document {doc.id}, it will not be included in the merge",
+                f"Error merging document {doc.id}, it will not be included in the merge: {e}",
            )
    if len(affected_docs) == 0:
        logger.warning("No documents were merged")
@@ -805,8 +805,8 @@ def split(
            else:
                group(consume_tasks).delay()

-    except Exception:
-        logger.exception(f"Error splitting document {doc.id}")
+    except Exception as e:
+        logger.exception(f"Error splitting document {doc.id}: {e}")

    return "OK"

@@ -858,8 +858,8 @@ def delete_pages(
        logger.info(
            f"Queued new version for document {pair.root_doc.id} after deleting pages {pages}",
        )
-    except Exception:
-        logger.exception(f"Error deleting pages from document {pair.root_doc.id}")
+    except Exception as e:
+        logger.exception(f"Error deleting pages from document {pair.root_doc.id}: {e}")

    return "OK"

@@ -986,7 +986,7 @@ def edit_pdf(
                group(consume_tasks).delay()

    except Exception as e:
-        logger.exception(f"Error editing document {pair.root_doc.id}")
+        logger.exception(f"Error editing document {pair.root_doc.id}: {e}")
        raise ValueError(
            f"An error occurred while editing the document: {e}",
        ) from e
@@ -1097,7 +1097,7 @@ def remove_password(

        except Exception as e:
            logger.exception(
-                f"Error removing password from document {pair.root_doc.id}",
+                f"Error removing password from document {pair.root_doc.id}: {e}",
            )
            raise ValueError(
                f"An error occurred while removing the password: {e}",
@@ -69,8 +69,8 @@ def load_classifier(*, raise_exception: bool = False) -> DocumentClassifier | No
        Path(settings.MODEL_FILE).unlink()
        classifier = None
        if raise_exception:
-            raise
-    except ClassifierModelCorruptError:
+            raise e
+    except ClassifierModelCorruptError as e:
        # there's something wrong with the model file.
        logger.exception(
            "Unrecoverable error while loading document "
@@ -79,17 +79,17 @@ def load_classifier(*, raise_exception: bool = False) -> DocumentClassifier | No
        Path(settings.MODEL_FILE).unlink()
        classifier = None
        if raise_exception:
-            raise
-    except OSError:
+            raise e
+    except OSError as e:
        logger.exception("IO error while loading document classification model")
        classifier = None
        if raise_exception:
-            raise
-    except Exception:  # pragma: no cover
+            raise e
+    except Exception as e:  # pragma: no cover
        logger.exception("Unknown error while loading document classification model")
        classifier = None
        if raise_exception:
-            raise
+            raise e

    return classifier

@@ -216,7 +216,7 @@ class ConsumerPluginMixin:
            current_progress,
            max_progress,
            document_id=document_id,
-            owner_id=self.metadata.owner_id or None,
+            owner_id=self.metadata.owner_id if self.metadata.owner_id else None,
            users_can_view=(self.metadata.view_users or [])
            + (self.metadata.change_users or []),
            groups_can_view=(self.metadata.view_groups or [])
@@ -674,7 +674,9 @@ class ConsumerPlugin(
                            document=document,
                            logging_group=self.logging_group,
                            classifier=classifier,
-                            original_file=self.unmodified_original or self.working_copy,
+                            original_file=self.unmodified_original
+                            if self.unmodified_original
+                            else self.working_copy,
                        )

                        # After everything is in the database, copy the files into
@@ -847,7 +849,7 @@ class ConsumerPlugin(
        else:
            stats = Path(self.input_doc.original_file).stat()
            create_date = timezone.make_aware(
-                datetime.datetime.fromtimestamp(stats.st_mtime),  # noqa: DTZ006 - make_aware() requires a naive datetime
+                datetime.datetime.fromtimestamp(stats.st_mtime),
            )
            self.log.debug(f"Creation date from st_mtime: {create_date}")

@@ -961,7 +963,7 @@ class ConsumerPlugin(
        try:
            copy_basic_file_stats(source, target)
        except Exception:  # pragma: no cover
-            self.log.debug("Unable to copy file stats from %s to %s", source, target)
+            pass


 class ConsumerPreflightPlugin(
@@ -78,9 +78,7 @@ class CollatePlugin(NoCleanupPluginMixin, NoSetupPluginMixin, ConsumeTaskPlugin)
            stats = staging.stat()
            # if the file is older than the timeout, we don't consider
            # it valid
-            if (
-                dt.datetime.now(tz=dt.UTC).timestamp() - stats.st_mtime
-            ) > TIMEOUT_SECONDS:
+            if (dt.datetime.now().timestamp() - stats.st_mtime) > TIMEOUT_SECONDS:
                logger.warning("Outdated double sided staging file exists, deleting it")
                staging.unlink()
            else:
@@ -136,7 +134,7 @@ class CollatePlugin(NoCleanupPluginMixin, NoSetupPluginMixin, ConsumeTaskPlugin)
            shutil.move(pdf_file, staging)
            # update access to modification time so we know if the file
            # is outdated when another file gets uploaded
-            timestamp = dt.datetime.now(tz=dt.UTC).timestamp()
+            timestamp = dt.datetime.now().timestamp()
            os.utime(staging, (timestamp, timestamp))
            logger.info(
                "Got scan with odd numbered pages of double-sided scan, moved it to %s",
@@ -734,7 +734,7 @@ class CustomFieldQueryParser:
        )

        # Check if any of the requested IDs are missing.
-        missing_ids = set(value) - {link.document_id for link in links}
+        missing_ids = set(value) - set(link.document_id for link in links)
        if missing_ids:
            # The result should be an empty set in this case.
            return Q(id__in=[])
@@ -631,25 +631,23 @@ class Command(BaseCommand):
                ):
                    # Process each change
                    for change_type, path in changes:
-                        resolved_path = Path(path).resolve()
+                        path = Path(path).resolve()
                        if change_type == Change.deleted:
                            # Consumed (or otherwise removed); a later file
                            # reusing this name must not be skipped as
                            # already-queued.
-                            queued.discard(resolved_path)
-                        if not resolved_path.is_file():
+                            queued.discard(path)
+                        if not path.is_file():
                            continue
-                        if resolved_path in queued:
+                        if path in queued:
                            # Already queued and awaiting consumption; a stray
                            # event (NAS metadata touch, AV scan, etc.) while
                            # the file sits on disk mid-consumption must not
                            # cause it to be queued a second time (GH #13511).
-                            logger.debug(
-                                f"Ignoring event for queued file: {resolved_path}",
-                            )
+                            logger.debug(f"Ignoring event for queued file: {path}")
                            continue
-                        logger.debug(f"Event: {change_type.name} for {resolved_path}")
-                        tracker.track(resolved_path, change_type)
+                        logger.debug(f"Event: {change_type.name} for {path}")
+                        tracker.track(path, change_type)

                    # Check for stable files
                    for stable_path in tracker.get_stable_files():
@@ -30,10 +30,6 @@ if TYPE_CHECKING:
 logger = logging.getLogger("paperless.matching")


-class UnsupportedWorkflowTriggerTypeError(Exception):
-    pass
-
-
 def log_reason(
    matching_model: MatchingModel | WorkflowTrigger,
    document: Document,
@@ -695,9 +691,7 @@ def document_matches_workflow(
                )
            else:
                # New trigger types need to be explicitly checked above
-                raise UnsupportedWorkflowTriggerTypeError(
-                    f"Trigger type {trigger_type} not yet supported",
-                )
+                raise Exception(f"Trigger type {trigger_type} not yet supported")

            if trigger_matched:
                logger.info(f"Document matched {trigger} from {workflow}")
@@ -377,7 +377,7 @@ class Document(SoftDeleteModel, ModelWithOwner):  # type: ignore[django-manager-
        from documents.versioning import versions_newest_first

        if hasattr(self, "effective_content"):
-            return self.effective_content
+            return getattr(self, "effective_content")

        if self.root_document_id is not None or self.pk is None:
            return self.content
@@ -41,7 +41,7 @@ def get_default_file_extension(mime_type: str) -> str:
            return supported[mime_type]

    ext = mimetypes.guess_extension(mime_type)
-    return ext or ""
+    return ext if ext else ""


 def is_file_ext_supported(ext: str) -> bool:
@@ -43,8 +43,8 @@ def _discover_parser_class() -> type[DateParserPluginBase]:
                valid_plugins.append(ep)
            else:
                logger.warning(f"Plugin {ep.name} does not subclass DateParser.")
-        except Exception:
-            logger.exception(f"Unable to load date parser plugin {ep.name}")
+        except Exception as e:
+            logger.exception(f"Unable to load date parser plugin {ep.name}: {e}")

    if not valid_plugins:
        return RegexDateParserPlugin
@@ -91,8 +91,8 @@ class DateParserPluginBase(ABC):
                },
                locales=self.config.languages,
            )
-        except Exception:
-            logger.exception(f"Error while parsing date string '{date_string}'")
+        except Exception as e:
+            logger.exception(f"Error while parsing date string '{date_string}': {e}")
            return None

    def _filter_date(
@@ -59,10 +59,11 @@ def safe_regex_match(pattern: str, text: str, *, flags: int = 0):
    try:
        validate_regex_pattern(pattern)
        compiled = regex.compile(pattern, flags=flags)
-    except (regex.error, ValueError):
+    except (regex.error, ValueError) as exc:
        logger.exception(
-            "Error while processing regular expression %s",
+            "Error while processing regular expression %s: %s",
            textwrap.shorten(pattern, width=80, placeholder="…"),
+            exc,
        )
        return None

@@ -85,10 +86,11 @@ def safe_regex_sub(pattern: str, repl: str, text: str, *, flags: int = 0) -> str
    try:
        validate_regex_pattern(pattern)
        compiled = regex.compile(pattern, flags=flags)
-    except (regex.error, ValueError):
+    except (regex.error, ValueError) as exc:
        logger.exception(
-            "Error while processing regular expression %s",
+            "Error while processing regular expression %s: %s",
            textwrap.shorten(pattern, width=80, placeholder="…"),
+            exc,
        )
        return None

@@ -1142,7 +1142,7 @@ def get_backend() -> TantivyBackend:
    Returns:
        Thread-safe singleton TantivyBackend instance
    """
-    global _backend, _backend_path  # noqa: PLW0603 - module-level singleton, no class to hold this state
+    global _backend, _backend_path

    current_path: Path = settings.INDEX_DIR

@@ -1173,7 +1173,7 @@ def reset_backend() -> None:
    Forces creation of a new backend instance on the next get_backend() call.
    Used for test isolation and when switching between different index directories.
    """
-    global _backend, _backend_path  # noqa: PLW0603 - module-level singleton, no class to hold this state
+    global _backend, _backend_path

    with _backend_lock:
        if _backend is not None:
@@ -240,7 +240,7 @@ def parse_user_query(
            DEFAULT_SEARCH_FIELDS,
            field_boosts=_FIELD_BOOSTS,
            # (prefix=True, distance=1, transposition_cost_one=True) — edit-distance fuzziness
-            fuzzy_fields=dict.fromkeys(DEFAULT_SEARCH_FIELDS, (True, 1, True)),
+            fuzzy_fields={f: (True, 1, True) for f in DEFAULT_SEARCH_FIELDS},
        )
        # 0.1 boost keeps fuzzy hits ranked below exact matches (intentional)
        clauses.append((tantivy.Occur.Should, tantivy.Query.boost_query(fuzzy, 0.1)))
@@ -433,7 +433,7 @@ class OwnedObjectSerializer(
            return set()

        ctype = ContentType.objects.get_for_model(first_obj)
-        object_pks = [obj.pk for obj in objects]
+        object_pks = list(obj.pk for obj in objects)
        pk_type = type(first_obj.pk)

        def get_pks_for_permission_type(model):
@@ -727,7 +727,7 @@ class TagSerializer(MatchingModelSerializer, OwnedObjectSerializer):
                self.instance.clean()
            except ValidationError as e:
                logger.debug("Tag parent validation failed: %s", e)
-                raise
+                raise e
            finally:
                self.instance.tn_parent = original_parent
        else:
@@ -737,7 +737,7 @@ class TagSerializer(MatchingModelSerializer, OwnedObjectSerializer):
                temp.clean()
            except ValidationError as e:
                logger.debug("Tag parent validation failed: %s", e)
-                raise
+                raise e

        return super().validate(attrs)

@@ -1147,7 +1147,7 @@ class DocumentSerializer(
    def to_representation(self, instance):
        doc = super().to_representation(instance)
        if "content" in self.fields and hasattr(instance, "effective_content"):
-            doc["content"] = instance.effective_content or ""
+            doc["content"] = getattr(instance, "effective_content") or ""
        if self.truncate_content and "content" in self.fields:
            doc["content"] = doc.get("content")[0:550]
        return doc
@@ -1857,8 +1857,8 @@ class BulkEditSerializer(
        if isinstance(custom_fields, dict):
            try:
                ids = [int(i[0]) for i in custom_fields.items()]
-            except Exception:
-                logger.exception("Error validating custom fields")
+            except Exception as e:
+                logger.exception(f"Error validating custom fields: {e}")
                raise serializers.ValidationError(
                    f"{name} must be a list of integers or a dict of id:value pairs, see the log for details",
                )
@@ -2056,12 +2056,13 @@ class BulkEditSerializer(
            for doc in docs:
                if "-" in doc:
                    pages.append(
-                        list(
-                            range(
+                        [
+                            x
+                            for x in range(
                                int(doc.split("-")[0]),
                                int(doc.split("-")[1]) + 1,
-                            ),
-                        ),
+                            )
+                        ],
                    )
                else:
                    pages.append([int(doc)])
@@ -2922,7 +2923,7 @@ class ShareLinkBundleSerializer(OwnedObjectSerializer):
        return share_link_bundle

    def get_document_count(self, obj: ShareLinkBundle) -> int:
-        return obj.document_total or obj.documents.count()
+        return getattr(obj, "document_total") or obj.documents.count()


 class BulkEditObjectsSerializer(SerializerWithPerms, SetPermissionsMixin):
@@ -636,7 +636,7 @@ def update_filename_and_move_files(
                #  so this is not the end of the world.
                # B: if moving the original file failed, nothing has changed
                #  anyway.
-                logger.exception("Error reverting document changes")
+                pass

            # restore old values on the instance
            instance.filename = old_filename
@@ -1101,11 +1101,10 @@ def _extract_input_data(
                if v is None or k.startswith("_"):
                    continue
                if isinstance(v, datetime.date):
-                    override_dict[k] = v.isoformat()
+                    v = v.isoformat()
                elif isinstance(v, Path):
-                    override_dict[k] = str(v)
-                else:
-                    override_dict[k] = v
+                    v = str(v)
+                override_dict[k] = v
            if override_dict:
                data["overrides"] = override_dict
        return data
@@ -217,9 +217,9 @@ def consume_file(
                overrides.filename or input_doc.original_file.name,
                self.request.id,
            ) as status_mgr,
-            TemporaryDirectory(dir=settings.SCRATCH_DIR) as tmp_dir_name,
+            TemporaryDirectory(dir=settings.SCRATCH_DIR) as tmp_dir,
        ):
-            tmp_dir = Path(tmp_dir_name)
+            tmp_dir = Path(tmp_dir)
            msg = None
            for plugin_class in plugins:
                plugin_name = plugin_class.NAME
@@ -261,7 +261,7 @@ def consume_file(
                    )

                except Exception as e:
-                    logger.exception(f"{plugin_name} failed")
+                    logger.exception(f"{plugin_name} failed: {e}")
                    status_mgr.send_progress(
                        ProgressStatusOptions.FAILED,
                        f"{e}",
@@ -495,8 +495,8 @@ def empty_trash(doc_ids=None) -> None:
                content_type=ContentType.objects.get_for_model(Document),
                object_id__in=deleted_document_ids,
            ).delete()
-    except Exception:  # pragma: no cover
-        logger.exception("Error while emptying trash")
+    except Exception as e:  # pragma: no cover
+        logger.exception(f"Error while emptying trash: {e}")
    finally:
        models.signals.post_delete.disconnect(
            cleanup_document_deletion,
@@ -832,8 +832,9 @@ def build_share_link_bundle(bundle_id: int) -> None:
        logger.info("Built share link bundle %s", bundle.pk)
    except Exception as exc:
        logger.exception(
-            "Failed to build share link bundle %s",
+            "Failed to build share link bundle %s: %s",
            bundle_id,
+            exc,
        )
        bundle.status = ShareLinkBundle.Status.FAILED
        bundle.last_error = {
@@ -78,10 +78,6 @@ class PlaceholderString(str):
    def __ne__(self, other) -> bool:
        return not self.__eq__(other)

-    def __hash__(self) -> int:
-        # Equal to both "-none-" and "none", so hash to a single canonical value
-        return hash("-none-")
-

 NO_VALUE_PLACEHOLDER = PlaceholderString("-none-")

@@ -138,9 +138,9 @@ def parse_w_workflow_placeholders(

        # We're good!
        return rendered_template
-    except UndefinedError:
+    except UndefinedError as e:
        # The undefined class logs this already for us
-        raise
+        raise e
    except TemplateSyntaxError as e:
        logger.warning(f"Template syntax error in title generation: {e}")
    except SecurityError as e:
@@ -150,5 +150,5 @@ def parse_w_workflow_placeholders(
        logger.warning(
            f"Invalid title format '{text}', workflow not applied: {e}",
        )
-        raise
+        raise e
    return None
@@ -296,7 +296,7 @@ class TestRegexDateParser:

            # simulate parse failure for malformed input
            if "99/99/9999" in date_string or "bad date" in date_string:
-                raise Exception("parse failed for malformed date")  # noqa: TRY002 - simulates a generic parser failure
+                raise Exception("parse failed for malformed date")

            return None

@@ -57,13 +57,13 @@ class MultiprocessCommand(PaperlessCommand):

    def handle(self, *args, **options):
        items = list(range(5))
-        results = list(
-            self.process_parallel(
-                _double_value,
-                items,
-                description="Processing...",
-            ),
-        )
+        results = []
+        for result in self.process_parallel(
+            _double_value,
+            items,
+            description="Processing...",
+        ):
+            results.append(result)
        successes = sum(1 for r in results if r.success)
        self.stdout.write(f"Successes: {successes}")

@@ -66,7 +66,7 @@ class TestWriteBatchLockRetry:
        )
        mock_sleep = mocker.patch(
            "documents.search._backend.time.sleep",
-            side_effect=sleep_values.append,
+            side_effect=lambda s: sleep_values.append(s),
        )

        # Should not raise — 4th attempt succeeds
@@ -111,7 +111,7 @@ class TestWriteBatchLockRetry:
        sleep_values: list[float] = []
        mocker.patch(
            "documents.search._backend.time.sleep",
-            side_effect=sleep_values.append,
+            side_effect=lambda s: sleep_values.append(s),
        )
        for _ in range(50):
            sleep_values.clear()
@@ -1003,8 +1003,8 @@ class TestBulkEditAPI(DirectoriesMixin, APITestCase):
            for correspondent in response.data[field]:
                self.assertEqual(correspondent["document_count"], 0)
            self.assertCountEqual(
-                (c["id"] for c in response.data[field]),
-                (c["id"] for c in Entity.objects.values("id")),
+                map(lambda c: c["id"], response.data[field]),
+                map(lambda c: c["id"], Entity.objects.values("id")),
            )

    def test_api_selection_data(self) -> None:
@@ -18,8 +18,8 @@ class MockOpenIDProvider:

    def get_brands(self):
        default_servers = [
-            {"id": "yahoo", "name": "Yahoo", "openid_url": "http://me.yahoo.com"},
-            {"id": "hyves", "name": "Hyves", "openid_url": "http://hyves.nl"},
+            dict(id="yahoo", name="Yahoo", openid_url="http://me.yahoo.com"),
+            dict(id="hyves", name="Hyves", openid_url="http://hyves.nl"),
        ]
        return default_servers

@@ -205,12 +205,12 @@ class TestBarcode(
            - Barcode is detected on page 1 (zero indexed)
        """

-        for test_filename in [
+        for test_file in [
            "patch-code-t-middle-reverse.pdf",
            "patch-code-t-middle-distorted.pdf",
            "patch-code-t-middle-fuzzy.pdf",
        ]:
-            test_file = self.BARCODE_SAMPLE_DIR / test_filename
+            test_file = self.BARCODE_SAMPLE_DIR / test_file

            with self.get_reader(test_file) as reader:
                reader.detect()
@@ -777,7 +777,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
        sig.set.return_value.apply_async.side_effect = Exception("boom")
        mock_consume_file.return_value = sig

-        with self.assertRaises(Exception):  # noqa: B017 - mock injects a bare Exception
+        with self.assertRaises(Exception):
            bulk_edit.merge(doc_ids, delete_originals=True)

        self.doc1.refresh_from_db()
@@ -1318,7 +1318,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
        sig.apply_async.side_effect = Exception("boom")
        mock_chord.return_value = sig

-        with self.assertRaises(Exception):  # noqa: B017 - mock injects a bare Exception
+        with self.assertRaises(Exception):
            bulk_edit.edit_pdf(doc_ids, operations, delete_original=True)

        self.doc2.refresh_from_db()
@@ -1430,7 +1430,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
            {"page": 9999},  # invalid page, forces error during PDF load
        ]
        with self.assertLogs("paperless.bulk_edit", level="ERROR"):
-            with self.assertRaises(ValueError):
+            with self.assertRaises(Exception):
                bulk_edit.edit_pdf(doc_ids, operations)
        mock_group.assert_not_called()
        mock_consume_file.assert_not_called()
@@ -783,7 +783,7 @@ class TestClassifier(DirectoriesMixin, TestCase):

        Path(settings.MODEL_FILE).touch()
        mock_load.side_effect = Exception()
-        with self.assertRaises(Exception):  # noqa: B017 - mock injects a bare Exception
+        with self.assertRaises(Exception):
            load_classifier(raise_exception=True)


@@ -137,7 +137,7 @@ class FaultyParser(_BaseNewStyleParser):

 class FaultyGenericExceptionParser(_BaseNewStyleParser):
    def parse(self, document_path, mime_type, *, produce_archive: bool = True) -> None:
-        raise Exception("Generic exception.")  # noqa: TRY002 - deliberately not a ParseError
+        raise Exception("Generic exception.")


 def fake_magic_from_file(file, *, mime=False):  # NOSONAR
@@ -1333,7 +1333,7 @@ class PreConsumeTestCase(DirectoriesMixin, GetConsumerMixin, TestCase):
            script_calls = [
                call
                for call in m.call_args_list
-                if call.args and call.args[0] and call.args[0][0] != "pdftotext"
+                if call.args and call.args[0] and call.args[0][0] not in ("pdftotext",)
            ]
            self.assertEqual(script_calls, [])

@@ -44,7 +44,6 @@ from documents import tasks
 from documents.data_models import ConsumableDocument
 from documents.data_models import DocumentMetadataOverrides
 from documents.data_models import DocumentSource
-from documents.matching import UnsupportedWorkflowTriggerTypeError
 from documents.matching import document_matches_workflow
 from documents.matching import existing_document_matches_workflow
 from documents.matching import prefilter_documents_by_workflowtrigger
@@ -2852,13 +2851,7 @@ class TestWorkflows(
        doc = Document.objects.create(
            title="test",
        )
-        self.assertRaises(
-            UnsupportedWorkflowTriggerTypeError,
-            document_matches_workflow,
-            doc,
-            w,
-            99,
-        )
+        self.assertRaises(Exception, document_matches_workflow, doc, w, 99)

    def test_removal_action_document_updated_workflow(self) -> None:
        """
@@ -21,32 +21,28 @@ def uri_validator(value: str, allowed_schemes: set[str] | None = None) -> None:
        parts = urlparse(value)
        if not parts.scheme:
            raise ValidationError(
-                _("Unable to parse URI %(value)s, missing scheme"),
+                _(f"Unable to parse URI {value}, missing scheme"),
                params={"value": value},
            )
        elif not parts.netloc and not parts.path:
            raise ValidationError(
-                _("Unable to parse URI %(value)s, missing net location or path"),
+                _(f"Unable to parse URI {value}, missing net location or path"),
                params={"value": value},
            )

        if allowed_schemes and parts.scheme not in allowed_schemes:
            raise ValidationError(
                _(
-                    "URI scheme '%(scheme)s' is not allowed. Allowed schemes: %(allowed_schemes)s",
+                    f"URI scheme '{parts.scheme}' is not allowed. Allowed schemes: {', '.join(allowed_schemes)}",
                ),
-                params={
-                    "value": value,
-                    "scheme": parts.scheme,
-                    "allowed_schemes": ", ".join(allowed_schemes),
-                },
+                params={"value": value, "scheme": parts.scheme},
            )

    except ValidationError:
        raise
    except Exception as e:
        raise ValidationError(
-            _("Unable to parse URI %(value)s"),
+            _(f"Unable to parse URI {value}"),
            params={"value": value},
        ) from e

@@ -1440,7 +1440,7 @@ class DocumentViewSet(
        try:
            lang = detect(doc.content)
        except Exception:
-            logger.debug("Unable to detect language for document %s", doc.pk)
+            pass
        meta["lang"] = lang

        return Response(meta)
@@ -1478,12 +1478,13 @@ class DocumentViewSet(
            with get_date_parser() as date_parser:
                gen = date_parser.parse(doc.filename, doc.content)
                dates = sorted(
-                    set(
-                        itertools.islice(
+                    {
+                        i
+                        for i in itertools.islice(
                            gen,
                            settings.NUMBER_OF_SUGGESTED_DATES,
-                        ),
-                    ),
+                        )
+                    },
                )

        resp_data = {
@@ -1567,16 +1568,21 @@ class DocumentViewSet(
            except ValueError as exc:
                logger.exception(
                    "Invalid AI configuration while generating suggestions for "
-                    "document %s",
+                    "document %s: %s",
                    doc.pk,
+                    exc,
+                    exc_info=True,
                )
                raise ValidationError(
                    {"ai": [_("Invalid AI configuration.")]},
                ) from exc
-            except LLMTimeoutError:
+            except LLMTimeoutError as exc:
                logger.exception(
-                    "AI backend timed out while generating suggestions for document %s",
+                    "AI backend timed out while generating suggestions for "
+                    "document %s: %s",
                    doc.pk,
+                    exc,
+                    exc_info=True,
                )
                return Response(
                    {"ai": [_("AI backend request timed out.")]},
@@ -2049,7 +2055,7 @@ class DocumentViewSet(
            doc_name, doc_data = serializer.validated_data.get("document")
            version_label = serializer.validated_data.get("version_label")

-            t = int(mktime(datetime.now().timetuple()))  # noqa: DTZ005 - mktime() requires a local time tuple
+            t = int(mktime(datetime.now().timetuple()))

            settings.SCRATCH_DIR.mkdir(parents=True, exist_ok=True)

@@ -3319,7 +3325,7 @@ class PostDocumentView(GenericAPIView[Any]):
        cf = serializer.validated_data.get("custom_fields")
        from_webui = serializer.validated_data.get("from_webui")

-        t = int(mktime(datetime.now().timetuple()))  # noqa: DTZ005 - mktime() requires a local time tuple
+        t = int(mktime(datetime.now().timetuple()))

        settings.SCRATCH_DIR.mkdir(parents=True, exist_ok=True)

@@ -4129,7 +4135,7 @@ class UiSettingsView(GenericAPIView[Any]):
            user_resp["last_name"] = user.last_name

        # strip <app_label>.
-        roles = (re.sub(r"^\w+.", "", perm) for perm in user.get_all_permissions())
+        roles = map(lambda perm: re.sub(r"^\w+.", "", perm), user.get_all_permissions())
        return Response(
            {
                "user": user_resp,
@@ -5156,11 +5162,11 @@ class SystemStatusView(PassUserMixin):
                f"{m.app}.{m.name}"
                for m in MigrationRecorder.Migration.objects.all().order_by("id")
            ]
-        except Exception:  # pragma: no cover
+        except Exception as e:  # pragma: no cover
            applied_migrations = []
            db_status = "ERROR"
            logger.exception(
-                "System status detected a possible problem while connecting to the database",
+                f"System status detected a possible problem while connecting to the database: {e}",
            )
            db_error = "Error connecting to database, check logs for more detail."

@@ -5176,10 +5182,10 @@ class SystemStatusView(PassUserMixin):
            try:
                client.ping()
                redis_status = "OK"
-            except Exception:
+            except Exception as e:
                redis_status = "ERROR"
                logger.exception(
-                    "System status detected a possible problem while connecting to redis",
+                    f"System status detected a possible problem while connecting to redis: {e}",
                )
                redis_error = "Error connecting to redis, check logs for more detail."

@@ -5209,10 +5215,10 @@ class SystemStatusView(PassUserMixin):
                else:
                    celery_active = "WARNING"
                    celery_error = "Celery worker responded unexpectedly."
-        except Exception:
+        except Exception as e:
            celery_active = "ERROR"
            logger.exception(
-                "System status detected a possible problem while connecting to celery",
+                f"System status detected a possible problem while connecting to celery: {e}",
            )
            celery_error = "Error connecting to celery, check logs for more detail."

@@ -5227,15 +5233,13 @@ class SystemStatusView(PassUserMixin):
            index_dir = settings.INDEX_DIR
            mtimes = [p.stat().st_mtime for p in index_dir.iterdir() if p.is_file()]
            index_last_modified = (
-                make_aware(datetime.fromtimestamp(max(mtimes)))  # noqa: DTZ006 - make_aware() requires a naive datetime
-                if mtimes
-                else None
+                make_aware(datetime.fromtimestamp(max(mtimes))) if mtimes else None
            )
-        except Exception:
+        except Exception as e:
            index_status = "ERROR"
            index_error = "Error opening index, check logs for more detail."
            logger.exception(
-                "System status detected a possible problem while opening the index",
+                f"System status detected a possible problem while opening the index: {e}",
            )
            index_last_modified = None

@@ -66,7 +66,7 @@ def build_workflow_action_context(
        else None
    )

-    filename = document.original_file or ""
+    filename = document.original_file if document.original_file else ""
    return {
        "title": overrides.title
        if overrides and overrides.title
@@ -179,9 +179,9 @@ def execute_email_action(
            f"Sent {n_messages} notification email(s) to {action.email.to}",
            extra={"group": logging_group},
        )
-    except Exception:
+    except Exception as e:
        logger.exception(
-            "Error occurred sending notification email",
+            f"Error occurred sending notification email: {e}",
            extra={"group": logging_group},
        )

@@ -265,9 +265,9 @@ def execute_webhook_action(
            f"Webhook to {action.webhook.url} queued",
            extra={"group": logging_group},
        )
-    except Exception:
+    except Exception as e:
        logger.exception(
-            "Error occurred sending webhook",
+            f"Error occurred sending webhook: {e}",
            extra={"group": logging_group},
        )

@@ -47,7 +47,7 @@ def resolve_date(dates: list[str]) -> date | None:
    """
    for value in dates:
        try:
-            return datetime.strptime(value, "%Y-%m-%d").date()  # noqa: DTZ007 - only the calendar date is used, time/tz is discarded
+            return datetime.strptime(value, "%Y-%m-%d").date()
        except (TypeError, ValueError):
            logger.debug("Ignoring unparsable suggested date %s", value)
    return None
@@ -70,6 +70,6 @@ def send_webhook(
        logger.error(
            f"Failed attempt sending webhook to {url}: {e}",
        )
-        raise
+        raise e
    finally:
        transport.close()
@@ -241,7 +241,7 @@ def check_v3_minimum_upgrade_version(
        return []

    logger = logging.getLogger(__name__)
-    last_applied = max(applied) if applied else "(none)"
+    last_applied = sorted(applied)[-1] if applied else "(none)"
    logger.error(
        "V3 upgrade check failed: last applied documents migration is %r. "
        "Expected '1075_workflowaction_order' (v2.20.15). "
@@ -341,7 +341,6 @@ def get_tesseract_langs():
    proc = subprocess.run(
        [shutil.which("tesseract"), "--list-langs"],
        capture_output=True,
-        check=False,
    )

    # Decode bytes to string, split on newlines, trim out the header
@@ -84,7 +84,7 @@ def get_parser_registry() -> ParserRegistry:
    ParserRegistry
        The shared registry singleton.
    """
-    global _registry, _discovery_complete  # noqa: PLW0603 - module-level singleton, no class to hold this state
+    global _registry, _discovery_complete

    with _lock:
        if _registry is None:
@@ -113,7 +113,7 @@ def init_builtin_parsers() -> None:
    -------
    None
    """
-    global _registry  # noqa: PLW0603 - module-level singleton, no class to hold this state
+    global _registry

    with _lock:
        if _registry is None:
@@ -137,7 +137,7 @@ def reset_parser_registry() -> None:
    -------
    None
    """
-    global _registry, _discovery_complete  # noqa: PLW0603 - module-level singleton, no class to hold this state
+    global _registry, _discovery_complete

    _registry = None
    _discovery_complete = False
@@ -76,7 +76,7 @@ class RemoteEngineConfig:
    def engine_is_valid(self) -> bool:
        """Return True when the engine is known and fully configured."""
        return (
-            self.engine == "azureai"
+            self.engine in ("azureai",)
            and self.api_key is not None
            and not (self.engine == "azureai" and self.endpoint is None)
        )
@@ -467,7 +467,7 @@ class RemoteDocumentParser:
            return result.content

        except Exception as e:
-            logger.exception("Azure AI Vision parsing failed")
+            logger.exception("Azure AI Vision parsing failed: %s", e)
            raise ParseError(f"Azure AI Vision parsing failed: {e}") from e

        finally:
@@ -306,9 +306,8 @@ def extract_pdf_metadata(

    for key, value in meta.items():
        if isinstance(value, list):
-            str_value = " ".join(str(e) for e in value)
-        else:
-            str_value = str(value)
+            value = " ".join(str(e) for e in value)
+        value = str(value)

        try:
            m = namespace_pattern.match(key)
@@ -330,7 +329,7 @@ def extract_pdf_metadata(
                    namespace=namespace,
                    prefix=meta.REVERSE_NS[namespace],
                    key=key_value,
-                    value=str_value,
+                    value=value,
                ),
            )
        except Exception as e:
@@ -294,7 +294,7 @@ if _CHANNELS_BACKEND.startswith("channels_redis."):
 ###############################################################################

 EMAIL_HOST: Final[str] = os.getenv("PAPERLESS_EMAIL_HOST", "localhost")
-EMAIL_PORT: Final[int] = get_int_from_env("PAPERLESS_EMAIL_PORT", 25)
+EMAIL_PORT: Final[int] = int(os.getenv("PAPERLESS_EMAIL_PORT", 25))
 EMAIL_HOST_USER: Final[str] = os.getenv("PAPERLESS_EMAIL_HOST_USER", "")
 EMAIL_HOST_PASSWORD: Final[str] = os.getenv("PAPERLESS_EMAIL_HOST_PASSWORD", "")
 DEFAULT_FROM_EMAIL: Final[str] = os.getenv("PAPERLESS_EMAIL_FROM", EMAIL_HOST_USER)
@@ -381,9 +381,8 @@ ACCOUNT_SESSION_REMEMBER = get_bool_from_env(
    "True",
 )
 SESSION_EXPIRE_AT_BROWSER_CLOSE = not ACCOUNT_SESSION_REMEMBER
-SESSION_COOKIE_AGE = get_int_from_env(
-    "PAPERLESS_SESSION_COOKIE_AGE",
-    60 * 60 * 24 * 7 * 3,
+SESSION_COOKIE_AGE = int(
+    os.getenv("PAPERLESS_SESSION_COOKIE_AGE", 60 * 60 * 24 * 7 * 3),
 )
 # https://docs.djangoproject.com/en/5.1/ref/settings/#std-setting-SESSION_ENGINE
 SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"
@@ -396,6 +395,7 @@ if AUTO_LOGIN_USERNAME:


 def _parse_remote_user_settings() -> str:
+    global MIDDLEWARE, AUTHENTICATION_BACKENDS, REST_FRAMEWORK
    enable = get_bool_from_env("PAPERLESS_ENABLE_HTTP_REMOTE_USER")
    enable_api = get_bool_from_env("PAPERLESS_ENABLE_HTTP_REMOTE_USER_API")
    if enable or enable_api:
@@ -454,6 +454,7 @@ if ALLOWED_HOSTS != ["*"]:


 def _parse_paperless_url():
+    global CSRF_TRUSTED_ORIGINS, CORS_ALLOWED_ORIGINS, ALLOWED_HOSTS
    url = os.getenv("PAPERLESS_URL")
    if url:
        CSRF_TRUSTED_ORIGINS.append(url)
@@ -613,8 +614,8 @@ USE_TZ = True

 LOGGING_DIR.mkdir(parents=True, exist_ok=True)

-LOGROTATE_MAX_SIZE = get_int_from_env("PAPERLESS_LOGROTATE_MAX_SIZE", 1024 * 1024)
-LOGROTATE_MAX_BACKUPS = get_int_from_env("PAPERLESS_LOGROTATE_MAX_BACKUPS", 20)
+LOGROTATE_MAX_SIZE = os.getenv("PAPERLESS_LOGROTATE_MAX_SIZE", 1024 * 1024)
+LOGROTATE_MAX_BACKUPS = os.getenv("PAPERLESS_LOGROTATE_MAX_BACKUPS", 20)

 LOGGING = {
    "version": 1,
@@ -810,15 +811,9 @@ IGNORABLE_FILES: Final[list[str]] = [
    "Thumbs.db",
 ]

-CONSUMER_POLLING_INTERVAL = get_float_from_env(
-    "PAPERLESS_CONSUMER_POLLING_INTERVAL",
-    0.0,
-)
+CONSUMER_POLLING_INTERVAL = float(os.getenv("PAPERLESS_CONSUMER_POLLING_INTERVAL", 0))

-CONSUMER_STABILITY_DELAY = get_float_from_env(
-    "PAPERLESS_CONSUMER_STABILITY_DELAY",
-    5.0,
-)
+CONSUMER_STABILITY_DELAY = float(os.getenv("PAPERLESS_CONSUMER_STABILITY_DELAY", 5))

 CONSUMER_DELETE_DUPLICATES = get_bool_from_env("PAPERLESS_CONSUMER_DELETE_DUPLICATES")

@@ -111,7 +111,7 @@ def parse_dict_from_str(
            return False

    settings: dict[str, Any] = copy.deepcopy(defaults) if defaults else {}
-    _type_map = type_map or {}
+    _type_map = type_map if type_map else {}

    if not env_str:
        return settings
@@ -114,17 +114,17 @@ def test_cache_hit_when_enabled() -> None:
    assert settings.CACHALOT_TIMEOUT == 1

    # Read a table to populate the cache
-    list(Tag.objects.values_list("id", flat=True))
+    list(list(Tag.objects.values_list("id", flat=True)))

    # Invalidate the cache then read the database, there should be DB hit
    invalidate_db_cache()
    with CaptureQueriesContext(connection) as ctx:
-        list(Tag.objects.values_list("id", flat=True))
+        list(list(Tag.objects.values_list("id", flat=True)))
    assert len(ctx)

    # Doing the same request again should hit the cache, not the DB
    with CaptureQueriesContext(connection) as ctx:
-        list(Tag.objects.values_list("id", flat=True))
+        list(list(Tag.objects.values_list("id", flat=True)))
    assert not len(ctx)

    # Wait the end of TTL
@@ -133,7 +133,7 @@ def test_cache_hit_when_enabled() -> None:

    # Read the DB again. The DB should be hit because the cache has expired
    with CaptureQueriesContext(connection) as ctx:
-        list(Tag.objects.values_list("id", flat=True))
+        list(list(Tag.objects.values_list("id", flat=True)))
    assert len(ctx)

    # Invalidate the cache at the end of test
@@ -149,7 +149,7 @@ def test_cache_is_disabled_by_default() -> None:
    # Read the table multiple times: the DB should always be hit without cache
    for _ in range(3):
        with CaptureQueriesContext(connection) as ctx:
-            list(Tag.objects.values_list("id", flat=True))
+            list(list(Tag.objects.values_list("id", flat=True)))
        assert len(ctx)

    # Invalidate the cache at the end of test
@@ -59,7 +59,7 @@ def test_ocr_to_dateparser_languages_exception(
            raise RuntimeError("Simulated error")

    with caplog.at_level(logging.WARNING):
-        monkeypatch.setattr(utils, "LocaleDataLoader", DummyLoader)
+        monkeypatch.setattr(utils, "LocaleDataLoader", lambda: DummyLoader())
        result = utils.ocr_to_dateparser_languages("eng+fra")
        assert result == []
        assert (
@@ -5,13 +5,14 @@ from django.conf import settings
 from django.contrib.auth.models import User

 from documents.models import Document
-from documents.permissions import get_objects_for_user_owner_aware
+from documents.permissions import permitted_object_ids
+from documents.permissions import restrict_queryset_to_visible
+from documents.permissions import user_is_unrestricted
 from paperless.config import AIConfig
 from paperless_ai.base_model import ClassificationSuggestions
 from paperless_ai.base_model import TaxonomyChoiceDict
 from paperless_ai.client import AIClient
 from paperless_ai.db import db_connection_released
-from paperless_ai.indexing import _node_document_ids
 from paperless_ai.indexing import retrieve_similar_nodes
 from paperless_ai.indexing import truncate_content
 from paperless_ai.prompts.context import ClassificationPromptContext
@@ -19,7 +20,9 @@ from paperless_ai.prompts.context import LocalizationPromptContext
 from paperless_ai.prompts.context import RagContextPromptContext
 from paperless_ai.prompts.render import render_prompt
 from paperless_ai.taxonomy import AssignedMetadata
+from paperless_ai.taxonomy import SimilarDocument
 from paperless_ai.taxonomy import TaxonomyCandidates
+from paperless_ai.taxonomy import _node_document_weights
 from paperless_ai.taxonomy import build_taxonomy_candidates
 from paperless_ai.taxonomy import empty_taxonomy_candidates
 from paperless_ai.taxonomy import format_taxonomy_for_prompt
@@ -39,6 +42,48 @@ logger = logging.getLogger("paperless_ai.rag_classifier")
 TAXONOMY_CANDIDATE_TOP_K = 15


+def _fulltext_similar_documents(
+    document: Document,
+    user: User | None,
+    top_k: int,
+) -> list[SimilarDocument]:
+    """Rank-based fallback when no embedding backend is configured. Uses
+    Tantivy's "More Like This" (term-overlap similarity) instead of vector
+    similarity - cruder, but far better than no candidates at all.
+    more_like_this_ids returns only a ranked ID list, no scores, so weight is
+    synthesized from rank (descending from top_k) rather than claiming a
+    similarity magnitude that doesn't exist. An unrestricted user (none, or an
+    active superuser - see user_is_unrestricted) is normalized to ``None``
+    before calling, since the backend's permission filter has no superuser
+    short-circuit of its own. Results are re-checked with
+    restrict_queryset_to_visible() since Tantivy's indexed permission fields
+    lag the DB via async reindexing.
+    """
+    from documents.search import get_backend
+
+    unrestricted = user_is_unrestricted(user)
+    search_user = None if unrestricted else user
+    backend = get_backend()
+    similar_ids = backend.more_like_this_ids(
+        document.pk,
+        user=search_user,
+        limit=top_k,
+    )
+    if not unrestricted:
+        allowed_ids = set(
+            restrict_queryset_to_visible(
+                Document.objects.filter(pk__in=similar_ids),
+                user,
+                "view_document",
+            ).values_list("pk", flat=True),
+        )
+        similar_ids = [doc_id for doc_id in similar_ids if doc_id in allowed_ids]
+    return [
+        SimilarDocument(document_id=doc_id, weight=float(top_k - rank))
+        for rank, doc_id in enumerate(similar_ids)
+    ]
+
+
 def get_language_name(language_code: str) -> str:
    normalized_language_code = language_code.lower()
    for code, name in settings.LANGUAGES:
@@ -147,45 +192,54 @@ def get_taxonomy_context(
    user: User | None = None,
    max_docs: int = 5,
 ) -> tuple[TaxonomyCandidates, AssignedMetadata, str]:
-    """One retrieval feeds both taxonomy candidates and RAG text context.
-    On any retrieval failure, degrades to empty candidates/context rather than
-    propagating the exception - a vector-store outage should not block
-    classification, only its RAG-assisted enrichment.
+    """One retrieval feeds both taxonomy candidates and RAG text context. Uses
+    vector similarity when an embedding backend is configured, otherwise
+    falls back to Tantivy full-text "More Like This" similarity - see
+    _fulltext_similar_documents. On any retrieval failure, degrades to empty
+    candidates/context rather than propagating the exception - neither a
+    vector-store outage nor a search-index issue should block classification,
+    only its context-assisted enrichment.
    """
    assigned = get_assigned_metadata(document, user)
+    ai_config = AIConfig()
    try:
-        # None means "no restriction" to retrieve_similar_nodes. A superuser
-        # (like no user at all) can see every document, so skip materializing
-        # every visible pk into a Python list and passing it through as an IN
-        # filter: for a large library that is a wasted quadratic scan in the
-        # vector store at best, and past ~32,763 documents a hard
-        # sqlite3.OperationalError (SQLite's bound-parameter limit) at worst.
-        # get_objects_for_user_owner_aware() would return every Document for a
-        # superuser anyway (guardian's own with_superuser shortcut), so this
-        # changes nothing about which documents are considered -- only how we
-        # get there.
-        visible_document_ids = (
-            None
-            if user is None or user.is_superuser
-            else list(
-                get_objects_for_user_owner_aware(
-                    user,
-                    "view_document",
-                    Document,
-                ).values_list("pk", flat=True),
+        if ai_config.llm_embedding_backend:
+            # None means "no restriction" to retrieve_similar_nodes. A superuser
+            # (like no user at all) can see every document, so skip materializing
+            # every visible pk into a Python list and passing it through as an IN
+            # filter: for a large library that is a wasted quadratic scan in the
+            # vector store at best, and past ~32,763 documents a hard
+            # sqlite3.OperationalError (SQLite's bound-parameter limit) at worst.
+            # permitted_object_ids() has its own superuser shortcut that would
+            # return every Document's id anyway, so this changes nothing about
+            # which documents are considered -- only how we get there.
+            visible_document_ids = (
+                None
+                if user is None or user.is_superuser
+                else list(permitted_object_ids(user, Document, "view_document"))
+            )
+            nodes = retrieve_similar_nodes(
+                document,
+                top_k=TAXONOMY_CANDIDATE_TOP_K,
+                document_ids=visible_document_ids,
+            )
+            similar_documents = _node_document_weights(nodes)
+        else:
+            # See _fulltext_similar_documents: it applies its own permission
+            # filter via `user`, so no visible-document-id list is needed here.
+            similar_documents = _fulltext_similar_documents(
+                document,
+                user,
+                top_k=TAXONOMY_CANDIDATE_TOP_K,
            )
-        )
-        nodes = retrieve_similar_nodes(
-            document,
-            top_k=TAXONOMY_CANDIDATE_TOP_K,
-            document_ids=visible_document_ids,
-        )

-        candidates = build_taxonomy_candidates(nodes, user)
+        candidates = build_taxonomy_candidates(similar_documents, user)

-        similar_docs = list(
-            Document.objects.filter(pk__in=_node_document_ids(nodes))[:max_docs],
-        )
+        similar_doc_ids = [s["document_id"] for s in similar_documents]
+        docs_by_id = Document.objects.in_bulk(similar_doc_ids)
+        similar_docs = [
+            docs_by_id[doc_id] for doc_id in similar_doc_ids if doc_id in docs_by_id
+        ][:max_docs]
        context_blocks = []
        for similar in similar_docs:
            text = similar.content[:1000] or ""
@@ -193,8 +247,8 @@ def get_taxonomy_context(
            context_blocks.append(f"TITLE: {title}\n{text}")
    except Exception:
        logger.exception(
-            "Failed to retrieve RAG neighbours for document %s; continuing "
-            "without taxonomy candidates or similar-document context.",
+            "Failed to retrieve similar-document context for document %s; "
+            "continuing without taxonomy candidates or similar-document context.",
            document.pk,
        )
        return empty_taxonomy_candidates(), assigned, ""
@@ -277,23 +331,14 @@ def get_ai_document_classification(
 ) -> ClassificationSuggestions:
    ai_config = AIConfig()

-    if ai_config.llm_embedding_backend:
-        candidates, assigned, context = get_taxonomy_context(document, user)
-        prompt = build_prompt_with_rag(
-            document,
-            ai_config,
-            candidates=candidates,
-            assigned=assigned,
-            context=context,
-        )
-    else:
-        candidates = empty_taxonomy_candidates()
-        prompt = build_prompt_without_rag(
-            document,
-            ai_config,
-            candidates=candidates,
-            assigned=get_assigned_metadata(document, user),
-        )
+    candidates, assigned, context = get_taxonomy_context(document, user)
+    prompt = build_prompt_with_rag(
+        document,
+        ai_config,
+        candidates=candidates,
+        assigned=assigned,
+        context=context,
+    )

    client = AIClient()
    # Hand the pooled DB connection back while the (slow) LLM query runs so it
@@ -103,8 +103,8 @@ def stream_chat_with_documents(
            documents,
            output_language=output_language,
        )
-    except Exception:
-        logger.exception("Failed to stream document chat response")
+    except Exception as e:
+        logger.exception("Failed to stream document chat response: %s", e)
        yield CHAT_ERROR_MESSAGE


@@ -33,6 +33,11 @@ class TaxonomyCandidate(TypedDict):
    weight: float


+class SimilarDocument(TypedDict):
+    document_id: int
+    weight: float
+
+
 class TaxonomyCandidates(TypedDict):
    tags: list[TaxonomyCandidate]
    document_types: list[TaxonomyCandidate]
@@ -105,10 +110,10 @@ def get_assigned_metadata(document: Document, user: User | None) -> AssignedMeta
    )


-def _node_document_weights(nodes: list["NodeWithScore"]) -> dict[int, float]:
-    """document_id -> that node's similarity score, summed if a document_id
-    appears more than once across the retrieved nodes (e.g. multiple chunks
-    of the same source document)."""
+def _node_document_weights(nodes: list["NodeWithScore"]) -> list[SimilarDocument]:
+    """Sum each node's similarity score into its document_id (a document can
+    appear via multiple chunks/nodes) and return one SimilarDocument per
+    distinct document_id."""
    weights: dict[int, float] = defaultdict(float)
    for node in nodes:
        document_id = node.metadata.get("document_id")
@@ -121,7 +126,10 @@ def _node_document_weights(nodes: list["NodeWithScore"]) -> dict[int, float]:
            weights[int(document_id)] += float(node.score or 0.0)
        except (TypeError, ValueError):  # pragma: no cover
            continue
-    return weights
+    return [
+        SimilarDocument(document_id=document_id, weight=weight)
+        for document_id, weight in weights.items()
+    ]


 def _visible_ranked_candidates(
@@ -157,21 +165,26 @@ def _visible_ranked_candidates(


 def build_taxonomy_candidates(
-    nodes: list["NodeWithScore"],
+    similar_documents: list[SimilarDocument],
    user: User | None,
 ) -> TaxonomyCandidates:
-    """Resolve each neighbour node's document_id to a live Document, read its
-    *current* tags/type/correspondent/storage_path via the ORM (never the
-    possibly-stale names cached in vector-index node metadata), weight each
-    distinct taxonomy object by aggregate neighbour similarity, permission-filter
+    """Resolve each similar document's id to a live Document, read its
+    *current* tags/type/correspondent/storage_path via the ORM (never any
+    possibly-stale names an adapter's source might have cached), weight each
+    distinct taxonomy object by aggregate similarity weight, permission-filter
    against what ``user`` can see, and return each category ranked by weight
-    and capped.
+    and capped. ``similar_documents`` may come from either the vector-RAG
+    adapter or the full-text fallback adapter - both produce this same shape.
    """
-
-    document_weights = _node_document_weights(nodes)
-    if not document_weights:
+    if not similar_documents:
        return empty_taxonomy_candidates()

+    # Both adapters guarantee at most one SimilarDocument per document_id, so
+    # this never silently drops a duplicate's weight.
+    document_weights: dict[int, float] = {
+        s["document_id"]: s["weight"] for s in similar_documents
+    }
+
    # Only .tags.all() needs prefetching (a reverse M2M, one extra query for
    # the whole batch). document_type/correspondent/storage_path are read
    # below via their *_id columns (neighbour.document_type_id, etc.), which
@@ -1,3 +1,4 @@
+from collections.abc import Generator
 from types import SimpleNamespace
 from unittest.mock import MagicMock
 from unittest.mock import patch
@@ -7,10 +8,13 @@ import pytest_mock
 from django.test import override_settings

 from documents.models import Document
+from documents.search import TantivyBackend
 from documents.tests.factories import DocumentFactory
 from documents.tests.factories import TagFactory
 from documents.tests.factories import UserFactory
 from paperless.config import AIConfig
+from paperless_ai.ai_classifier import TAXONOMY_CANDIDATE_TOP_K
+from paperless_ai.ai_classifier import _fulltext_similar_documents
 from paperless_ai.ai_classifier import _restrict_to_shown_candidates
 from paperless_ai.ai_classifier import build_localization_prompt
 from paperless_ai.ai_classifier import build_prompt_with_rag
@@ -20,6 +24,7 @@ from paperless_ai.ai_classifier import get_language_name
 from paperless_ai.ai_classifier import get_taxonomy_context
 from paperless_ai.base_model import ClassificationSuggestions
 from paperless_ai.base_model import TaxonomyChoiceDict
+from paperless_ai.taxonomy import SimilarDocument
 from paperless_ai.taxonomy import TaxonomyCandidate
 from paperless_ai.taxonomy import TaxonomyCandidates
 from paperless_ai.taxonomy import empty_taxonomy_candidates
@@ -167,7 +172,7 @@ def test_get_ai_document_classification_failure(mock_run_llm_query, mock_documen
    """
    mock_run_llm_query.side_effect = Exception("LLM query failed")

-    with pytest.raises(Exception):  # noqa: B017 - mock injects a bare Exception
+    with pytest.raises(Exception):
        get_ai_document_classification(mock_document)


@@ -204,12 +209,10 @@ def test_use_rag_if_configured(

@pytest.mark.django_db
@patch("paperless_ai.client.AIClient.run_llm_query")
-@patch("paperless_ai.ai_classifier.build_prompt_without_rag")
-@patch("paperless_ai.ai_classifier.AIConfig")
+@patch("paperless_ai.ai_classifier.build_prompt_with_rag")
@override_settings(LLM_BACKEND="ollama", LLM_MODEL="some_model")
-def test_use_without_rag_if_not_configured(
-    mock_ai_config,
-    mock_build_prompt_without_rag,
+def test_use_rag_prompt_even_without_embedding_backend(
+    mock_build_prompt_with_rag,
    mock_run_llm_query,
    mock_document,
 ):
@@ -219,13 +222,13 @@ def test_use_without_rag_if_not_configured(
    WHEN:
        - get_ai_document_classification() is called
    THEN:
-        - The non-RAG prompt builder is used
+        - The RAG-context prompt builder is still used (fed by the full-text
+          fallback's context/candidates instead of the vector store's)
    """
-    mock_ai_config.return_value.llm_embedding_backend = None
-    mock_build_prompt_without_rag.return_value = "Prompt without RAG"
+    mock_build_prompt_with_rag.return_value = "Prompt with RAG"
    mock_run_llm_query.return_value = NESTED_SUGGESTIONS
    get_ai_document_classification(mock_document)
-    mock_build_prompt_without_rag.assert_called_once()
+    mock_build_prompt_with_rag.assert_called_once()


@pytest.mark.django_db
@@ -303,6 +306,7 @@ def test_build_localization_prompt_preserves_unicode_characters():


@pytest.mark.django_db
+@override_settings(LLM_EMBEDDING_BACKEND="huggingface")
 def test_get_taxonomy_context_assembles_rag_text_and_candidates():
    """
    GIVEN:
@@ -344,6 +348,7 @@ def test_get_taxonomy_context_assembles_rag_text_and_candidates():


@pytest.mark.django_db
+@override_settings(LLM_EMBEDDING_BACKEND="huggingface")
 def test_get_taxonomy_context_no_similar_docs():
    """
    GIVEN:
@@ -367,6 +372,67 @@ def test_get_taxonomy_context_no_similar_docs():
    }


+@pytest.mark.django_db
+def test_get_taxonomy_context_uses_fulltext_fallback_when_no_embedding_backend(
+    mocker: pytest_mock.MockerFixture,
+) -> None:
+    """
+    GIVEN:
+        - No LLM embedding backend is configured (the default test settings)
+    WHEN:
+        - get_taxonomy_context() is called
+    THEN:
+        - _fulltext_similar_documents() is called with the document, the user
+          and TAXONOMY_CANDIDATE_TOP_K
+        - retrieve_similar_nodes() (the vector path) is never called
+    """
+    document = DocumentFactory.create(content="Some content")
+    mock_fulltext = mocker.patch(
+        "paperless_ai.ai_classifier._fulltext_similar_documents",
+        return_value=[],
+    )
+    mock_retrieve = mocker.patch("paperless_ai.ai_classifier.retrieve_similar_nodes")
+
+    get_taxonomy_context(document, user=None)
+
+    mock_fulltext.assert_called_once_with(
+        document,
+        None,
+        top_k=TAXONOMY_CANDIDATE_TOP_K,
+    )
+    mock_retrieve.assert_not_called()
+
+
+@pytest.mark.django_db
+@override_settings(LLM_EMBEDDING_BACKEND="huggingface")
+def test_get_taxonomy_context_uses_vector_path_when_embedding_backend_configured(
+    mocker: pytest_mock.MockerFixture,
+) -> None:
+    """
+    GIVEN:
+        - An LLM embedding backend is configured
+    WHEN:
+        - get_taxonomy_context() is called
+    THEN:
+        - retrieve_similar_nodes() (the vector path) is called
+        - _fulltext_similar_documents() (the no-embedding-backend fallback)
+          is never called
+    """
+    document = DocumentFactory.create(content="Some content")
+    mock_retrieve = mocker.patch(
+        "paperless_ai.ai_classifier.retrieve_similar_nodes",
+        return_value=[],
+    )
+    mock_fulltext = mocker.patch(
+        "paperless_ai.ai_classifier._fulltext_similar_documents",
+    )
+
+    get_taxonomy_context(document, user=None)
+
+    mock_retrieve.assert_called_once()
+    mock_fulltext.assert_not_called()
+
+
 class TestGetTaxonomyContextVisibility:
    """get_taxonomy_context must not materialize every visible document id
    for a user who can already see the whole library: a superuser (like no
@@ -379,6 +445,7 @@ class TestGetTaxonomyContextVisibility:
    """

    @pytest.mark.django_db
+    @override_settings(LLM_EMBEDDING_BACKEND="huggingface")
    def test_skips_permission_lookup_for_superuser(
        self,
        mocker: pytest_mock.MockerFixture,
@@ -397,17 +464,18 @@ class TestGetTaxonomyContextVisibility:
            "paperless_ai.ai_classifier.retrieve_similar_nodes",
            return_value=[],
        )
-        mock_get_objects = mocker.patch(
-            "paperless_ai.ai_classifier.get_objects_for_user_owner_aware",
+        mock_permitted = mocker.patch(
+            "paperless_ai.ai_classifier.permitted_object_ids",
        )
        user = UserFactory.create(is_superuser=True)

        get_taxonomy_context(document, user)

-        mock_get_objects.assert_not_called()
+        mock_permitted.assert_not_called()
        assert mock_retrieve.call_args.kwargs["document_ids"] is None

    @pytest.mark.django_db
+    @override_settings(LLM_EMBEDDING_BACKEND="huggingface")
    def test_skips_permission_lookup_when_no_user(
        self,
        mocker: pytest_mock.MockerFixture,
@@ -426,16 +494,17 @@ class TestGetTaxonomyContextVisibility:
            "paperless_ai.ai_classifier.retrieve_similar_nodes",
            return_value=[],
        )
-        mock_get_objects = mocker.patch(
-            "paperless_ai.ai_classifier.get_objects_for_user_owner_aware",
+        mock_permitted = mocker.patch(
+            "paperless_ai.ai_classifier.permitted_object_ids",
        )

        get_taxonomy_context(document, None)

-        mock_get_objects.assert_not_called()
+        mock_permitted.assert_not_called()
        assert mock_retrieve.call_args.kwargs["document_ids"] is None

    @pytest.mark.django_db
+    @override_settings(LLM_EMBEDDING_BACKEND="huggingface")
    def test_restricts_to_visible_documents_for_non_superuser(
        self,
        mocker: pytest_mock.MockerFixture,
@@ -446,7 +515,7 @@ class TestGetTaxonomyContextVisibility:
        WHEN:
            - get_taxonomy_context() is called
        THEN:
-            - The user's visible document ids are looked up and passed to
+            - The user's permitted document ids are looked up and passed to
              retrieve_similar_nodes() as a restriction
        """
        document = DocumentFactory.create(content="Some content")
@@ -454,21 +523,186 @@ class TestGetTaxonomyContextVisibility:
            "paperless_ai.ai_classifier.retrieve_similar_nodes",
            return_value=[],
        )
-        mock_queryset = mocker.MagicMock()
-        mock_queryset.values_list.return_value = [1, 2, 3]
-        mock_get_objects = mocker.patch(
-            "paperless_ai.ai_classifier.get_objects_for_user_owner_aware",
-            return_value=mock_queryset,
+        mock_permitted = mocker.patch(
+            "paperless_ai.ai_classifier.permitted_object_ids",
+            return_value=[1, 2, 3],
        )
        user = UserFactory.create(is_superuser=False)

        get_taxonomy_context(document, user)

-        mock_get_objects.assert_called_once_with(user, "view_document", Document)
+        mock_permitted.assert_called_once_with(user, Document, "view_document")
        assert mock_retrieve.call_args.kwargs["document_ids"] == [1, 2, 3]


@pytest.mark.django_db
+class TestFulltextSimilarDocuments:
+    """_fulltext_similar_documents is the no-embedding-backend fallback: it
+    asks the Tantivy full-text index for "More Like This" neighbours instead
+    of the vector store, and synthesizes a rank-based weight since Tantivy's
+    more_like_this_ids returns only an ordered id list, no scores.
+    """
+
+    @pytest.fixture
+    def fulltext_backend(
+        self,
+        mocker: pytest_mock.MockerFixture,
+    ) -> Generator[TantivyBackend, None, None]:
+        """An in-memory Tantivy backend, wired up as the module-level
+        singleton _fulltext_similar_documents resolves via get_backend()."""
+        backend = TantivyBackend(path=None)
+        backend.open()
+        mocker.patch("documents.search.get_backend", return_value=backend)
+        try:
+            yield backend
+        finally:
+            backend.close()
+
+    def test_ranks_by_rank_based_weight_descending(
+        self,
+        fulltext_backend: TantivyBackend,
+    ) -> None:
+        """
+        GIVEN:
+            - A source document and two similar documents indexed in Tantivy
+        WHEN:
+            - _fulltext_similar_documents() is called
+        THEN:
+            - Each result's weight reflects its rank (first result weighted
+              higher than the second), not a raw similarity score
+        """
+        source = DocumentFactory.create(content="quarterly financial report details")
+        first = DocumentFactory.create(content="quarterly financial report details")
+        second = DocumentFactory.create(content="financial report")
+        for doc in (source, first, second):
+            fulltext_backend.add_or_update(doc)
+
+        result = _fulltext_similar_documents(source, user=None, top_k=5)
+
+        assert len(result) == 2
+        weight_by_id = {s["document_id"]: s["weight"] for s in result}
+        assert weight_by_id[first.pk] > weight_by_id[second.pk]
+
+    def test_excludes_source_document(
+        self,
+        fulltext_backend: TantivyBackend,
+    ) -> None:
+        """
+        GIVEN:
+            - A source document indexed in Tantivy with no other documents
+        WHEN:
+            - _fulltext_similar_documents() is called
+        THEN:
+            - An empty list is returned - the source document is never its
+              own similar document
+        """
+        source = DocumentFactory.create(content="unique unrelated content")
+        fulltext_backend.add_or_update(source)
+
+        result = _fulltext_similar_documents(source, user=None, top_k=5)
+
+        assert result == []
+
+    def test_empty_index_returns_empty_list(
+        self,
+        fulltext_backend: TantivyBackend,
+    ) -> None:
+        """
+        GIVEN:
+            - A document that has never been indexed (fresh/empty Tantivy index)
+        WHEN:
+            - _fulltext_similar_documents() is called
+        THEN:
+            - An empty list is returned rather than raising
+        """
+        source = DocumentFactory.create(content="never indexed")
+
+        result = _fulltext_similar_documents(source, user=None, top_k=5)
+
+        assert result == []
+
+    def test_respects_top_k_limit(
+        self,
+        fulltext_backend: TantivyBackend,
+    ) -> None:
+        """
+        GIVEN:
+            - A source document and four similar documents indexed
+        WHEN:
+            - _fulltext_similar_documents() is called with top_k=2
+        THEN:
+            - At most 2 results are returned
+        """
+        source = DocumentFactory.create(content="shared overlapping keyword text")
+        fulltext_backend.add_or_update(source)
+        for _ in range(4):
+            fulltext_backend.add_or_update(
+                DocumentFactory.create(content="shared overlapping keyword text"),
+            )
+
+        result = _fulltext_similar_documents(source, user=None, top_k=2)
+
+        assert len(result) == 2
+
+    def test_result_shape_is_similar_document(
+        self,
+        fulltext_backend: TantivyBackend,
+    ) -> None:
+        """
+        GIVEN:
+            - A source document and one similar document indexed
+        WHEN:
+            - _fulltext_similar_documents() is called
+        THEN:
+            - Each result is a SimilarDocument (document_id + weight only)
+        """
+        source = DocumentFactory.create(content="shared content phrase")
+        other = DocumentFactory.create(content="shared content phrase")
+        fulltext_backend.add_or_update(source)
+        fulltext_backend.add_or_update(other)
+
+        result = _fulltext_similar_documents(source, user=None, top_k=5)
+
+        # rank 0 (the only/best result) with top_k=5 -> weight = top_k - rank = 5.0,
+        # per the "first result gets top_k, the last gets 1" formula.
+        assert result == [SimilarDocument(document_id=other.pk, weight=5.0)]
+
+    def test_superuser_sees_other_users_documents(
+        self,
+        fulltext_backend: TantivyBackend,
+    ) -> None:
+        """
+        GIVEN:
+            - A source document owned by one user and a similar document
+              owned by a different user, with no sharing between them
+        WHEN:
+            - _fulltext_similar_documents() is called with a superuser
+        THEN:
+            - The other user's document is still returned as a similar
+              document - a superuser must not be narrowed by the backend's
+              owner-based permission filter
+        """
+        owner = UserFactory.create()
+        other_owner = UserFactory.create()
+        superuser = UserFactory.create(is_superuser=True)
+        source = DocumentFactory.create(
+            content="shared content phrase",
+            owner=owner,
+        )
+        other = DocumentFactory.create(
+            content="shared content phrase",
+            owner=other_owner,
+        )
+        fulltext_backend.add_or_update(source)
+        fulltext_backend.add_or_update(other)
+
+        result = _fulltext_similar_documents(source, user=superuser, top_k=5)
+
+        assert [s["document_id"] for s in result] == [other.pk]
+
+
+@pytest.mark.django_db
+@override_settings(LLM_EMBEDDING_BACKEND="huggingface")
@patch("paperless_ai.ai_classifier.retrieve_similar_nodes")
 def test_get_taxonomy_context_retrieval_failure_degrades_to_no_hints(mock_retrieve):
    """
@@ -495,6 +729,7 @@ def test_get_taxonomy_context_retrieval_failure_degrades_to_no_hints(mock_retrie


@pytest.mark.django_db
+@override_settings(LLM_EMBEDDING_BACKEND="huggingface")
@patch("paperless_ai.ai_classifier.build_taxonomy_candidates")
@patch("paperless_ai.ai_classifier.retrieve_similar_nodes")
 def test_get_taxonomy_context_candidate_building_failure_degrades_to_no_hints(
@@ -21,6 +21,5 @@ class TestLazyAiImports:
            capture_output=True,
            text=True,
            cwd=_SRC_DIR,
-            check=False,
        )
        assert result.returncode == 0, result.stdout + result.stderr
@@ -1,5 +1,4 @@
 import json
-from types import SimpleNamespace

 import pytest
 import pytest_mock
@@ -11,6 +10,7 @@ from documents.tests.factories import StoragePathFactory
 from documents.tests.factories import TagFactory
 from documents.tests.factories import UserFactory
 from paperless_ai.taxonomy import AssignedMetadata
+from paperless_ai.taxonomy import SimilarDocument
 from paperless_ai.taxonomy import TaxonomyCandidates
 from paperless_ai.taxonomy import build_taxonomy_candidates
 from paperless_ai.taxonomy import format_taxonomy_for_prompt
@@ -132,9 +132,8 @@ class TestGetAssignedMetadata:
        assert result["tags"] == ["Owned By Someone Else"]


-def make_node(document_id: int, score: float) -> SimpleNamespace:
-    """A stand-in for NodeWithScore: only ``.metadata``/``.score`` are read."""
-    return SimpleNamespace(metadata={"document_id": str(document_id)}, score=score)
+def make_similar(document_id: int, weight: float) -> SimilarDocument:
+    return SimilarDocument(document_id=document_id, weight=weight)


@pytest.mark.django_db
@@ -170,9 +169,9 @@ class TestBuildTaxonomyCandidates:
        doc_a.tags.add(tag)
        doc_b = DocumentFactory.create()
        doc_b.tags.add(tag)
-        nodes = [make_node(doc_a.pk, 0.9), make_node(doc_b.pk, 0.4)]
+        similar_documents = [make_similar(doc_a.pk, 0.9), make_similar(doc_b.pk, 0.4)]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert len(result["tags"]) == 1
        assert result["tags"][0]["id"] == tag.pk
@@ -197,9 +196,9 @@ class TestBuildTaxonomyCandidates:
        document.tags.add(tag)
        tag.name = "New Name"
        tag.save()
-        nodes = [make_node(document.pk, 0.5)]
+        similar_documents = [make_similar(document.pk, 0.5)]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert result["tags"][0]["name"] == "New Name"

@@ -219,9 +218,9 @@ class TestBuildTaxonomyCandidates:
        document = DocumentFactory.create()
        document.tags.add(tag)
        tag.delete()
-        nodes = [make_node(document.pk, 0.5)]
+        similar_documents = [make_similar(document.pk, 0.5)]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert result["tags"] == []

@@ -240,9 +239,12 @@ class TestBuildTaxonomyCandidates:
        strong_doc.tags.add(strong_tag)
        weak_doc = DocumentFactory.create()
        weak_doc.tags.add(weak_tag)
-        nodes = [make_node(strong_doc.pk, 0.9), make_node(weak_doc.pk, 0.1)]
+        similar_documents = [
+            make_similar(strong_doc.pk, 0.9),
+            make_similar(weak_doc.pk, 0.1),
+        ]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert [c["name"] for c in result["tags"]] == ["Strong", "Weak"]

@@ -258,9 +260,9 @@ class TestBuildTaxonomyCandidates:
        document = DocumentFactory.create()
        for i in range(15):
            document.tags.add(TagFactory.create(name=f"Tag{i}"))
-        nodes = [make_node(document.pk, 0.5)]
+        similar_documents = [make_similar(document.pk, 0.5)]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert len(result["tags"]) == 10

@@ -274,12 +276,12 @@ class TestBuildTaxonomyCandidates:
            - Only 5 correspondents are returned
        """
        correspondents = CorrespondentFactory.create_batch(7)
-        nodes = [
-            make_node(DocumentFactory.create(correspondent=c).pk, 0.5)
+        similar_documents = [
+            make_similar(DocumentFactory.create(correspondent=c).pk, 0.5)
            for c in correspondents
        ]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert len(result["correspondents"]) == 5

@@ -294,9 +296,9 @@ class TestBuildTaxonomyCandidates:
        """
        document_type = DocumentTypeFactory.create(name="Invoice")
        document = DocumentFactory.create(document_type=document_type)
-        nodes = [make_node(document.pk, 0.5)]
+        similar_documents = [make_similar(document.pk, 0.5)]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert len(result["document_types"]) == 1
        assert result["document_types"][0]["id"] == document_type.pk
@@ -312,12 +314,12 @@ class TestBuildTaxonomyCandidates:
            - Only 5 document_types are returned
        """
        document_types = DocumentTypeFactory.create_batch(7)
-        nodes = [
-            make_node(DocumentFactory.create(document_type=dt).pk, 0.5)
+        similar_documents = [
+            make_similar(DocumentFactory.create(document_type=dt).pk, 0.5)
            for dt in document_types
        ]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert len(result["document_types"]) == 5

@@ -332,9 +334,9 @@ class TestBuildTaxonomyCandidates:
        """
        storage_path = StoragePathFactory.create(name="Invoices")
        document = DocumentFactory.create(storage_path=storage_path)
-        nodes = [make_node(document.pk, 0.5)]
+        similar_documents = [make_similar(document.pk, 0.5)]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert len(result["storage_paths"]) == 1
        assert result["storage_paths"][0]["id"] == storage_path.pk
@@ -350,12 +352,12 @@ class TestBuildTaxonomyCandidates:
            - Only 5 storage_paths are returned
        """
        storage_paths = StoragePathFactory.create_batch(7)
-        nodes = [
-            make_node(DocumentFactory.create(storage_path=sp).pk, 0.5)
+        similar_documents = [
+            make_similar(DocumentFactory.create(storage_path=sp).pk, 0.5)
            for sp in storage_paths
        ]

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert len(result["storage_paths"]) == 5

@@ -375,14 +377,14 @@ class TestBuildTaxonomyCandidates:
        tag = TagFactory.create(name="Restricted")
        document = DocumentFactory.create()
        document.tags.add(tag)
-        nodes = [make_node(document.pk, 0.5)]
+        similar_documents = [make_similar(document.pk, 0.5)]
        user = UserFactory.create()
        mocker.patch(
            "documents.permissions.permitted_object_ids",
            return_value=[],  # user cannot see this tag
        )

-        result = build_taxonomy_candidates(nodes, user=user)
+        result = build_taxonomy_candidates(similar_documents, user=user)

        assert result["tags"] == []

@@ -412,10 +414,10 @@ class TestBuildTaxonomyCandidates:
        tag.save()
        document = DocumentFactory.create()
        document.tags.add(tag)
-        nodes = [make_node(document.pk, 0.5)]
+        similar_documents = [make_similar(document.pk, 0.5)]
        spy = mocker.patch("documents.permissions.permitted_object_ids")

-        result = build_taxonomy_candidates(nodes, user=None)
+        result = build_taxonomy_candidates(similar_documents, user=None)

        assert result["tags"][0]["name"] == "Owned"
        spy.assert_not_called()
@@ -7,6 +7,7 @@ import ssl
 import tempfile
 import traceback
 import unicodedata
+from datetime import date
 from datetime import timedelta
 from fnmatch import fnmatch
 from pathlib import Path
@@ -405,7 +406,7 @@ def make_criterias(rule: MailRule, *, supports_gmail_labels: bool):
    Returns criteria to be applied to MailBox.fetch for the given rule.
    """

-    maximum_age = timezone.localdate() - timedelta(days=rule.maximum_age)
+    maximum_age = date.today() - timedelta(days=rule.maximum_age)
    criterias = {}
    if rule.maximum_age > 0:
        criterias["date_gte"] = maximum_age
@@ -722,9 +723,9 @@ class MailAccountHandler(LoggingMixin):
                                f"Rule {rule}: Stopping processing rules due to stop_processing flag",
                            )
                            break
-                    except Exception:
+                    except Exception as e:
                        self.log.exception(
-                            f"Rule {rule}: Error while processing rule",
+                            f"Rule {rule}: Error while processing rule: {e}",
                        )
        except MailError:
            raise
@@ -873,9 +874,9 @@ class MailAccountHandler(LoggingMixin):

                total_processed_files += processed_files
                mails_processed += 1
-            except Exception:
+            except Exception as e:
                self.log.exception(
-                    f"Rule {rule}: Error while processing mail {message.uid}",
+                    f"Rule {rule}: Error while processing mail {message.uid}: {e}",
                )

        self.log.debug(f"Rule {rule}: Processed {mails_processed} matching mail(s)")
@@ -11,10 +11,6 @@ from imap_tools import MailMessage
 from documents.loggers import LoggingMixin


-class MailDecryptionError(Exception):
-    pass
-
-
 class MailMessagePreprocessor(abc.ABC):
    """
    Defines the interface for preprocessors that alter messages before they are handled in MailAccountHandler
@@ -73,7 +69,7 @@ class MailMessageDecryptor(MailMessagePreprocessor, LoggingMixin):
                f"Message decryption failed with status message "
                f"{decrypted_raw_message.status}",
            )
-            raise MailDecryptionError(
+            raise Exception(
                f"Decryption failed: {decrypted_raw_message.status}, {decrypted_raw_message.stderr}",
            )
        self.log.debug("Message decrypted successfully.")
@@ -50,7 +50,7 @@ class ProcessedMailFactory(DjangoModelFactory[ProcessedMail]):

    rule = factory.SubFactory(MailRuleFactory)
    folder = "INBOX"
-    uid = factory.Sequence(str)
+    uid = factory.Sequence(lambda n: str(n))
    subject = factory.Faker("sentence", nb_words=4)
    received = factory.LazyFunction(timezone.now)
    processed = factory.LazyFunction(timezone.now)
@@ -214,7 +214,7 @@ class BogusMailBox(AbstractContextManager):
            )
            self.messages = list(filter(lambda m: m.uid not in uid_list, self.messages))
        else:
-            raise Exception  # noqa: TRY002 - test double simulating a generic mailbox failure
+            raise Exception


 def fake_magic_from_buffer(buffer, *, mime=False):
@@ -14,7 +14,6 @@ from imap_tools import MailMessage

 from paperless_mail.mail import MailAccountHandler
 from paperless_mail.models import MailRule
-from paperless_mail.preprocessor import MailDecryptionError
 from paperless_mail.preprocessor import MailMessageDecryptor
 from paperless_mail.tests.factories import MailAccountFactory
 from paperless_mail.tests.test_mail import TestMail
@@ -83,9 +82,7 @@ class MessageEncryptor:
            armor=True,
        )
        if not encrypted_data.ok:
-            raise Exception(  # noqa: TRY002 - test fixture setup, not production code
-                f"Encryption failed: {encrypted_data.stderr}",
-            )
+            raise Exception(f"Encryption failed: {encrypted_data.stderr}")
        encrypted_email_content = encrypted_data.data

        new_email = MIMEMultipart("encrypted", protocol="application/pgp-encrypted")
@@ -187,11 +184,7 @@ class TestMailMessageGpgDecryptor(TestMail):
                EMAIL_GNUPG_HOME=empty_gpg_home,
            ):
                message_decryptor = MailMessageDecryptor()
-                self.assertRaises(
-                    MailDecryptionError,
-                    message_decryptor.run,
-                    encrypted_message,
-                )
+                self.assertRaises(Exception, message_decryptor.run, encrypted_message)
        finally:
            # Clean up the temporary GPG home used only by this test
            try:
@@ -1,3 +1,4 @@
+import datetime
 import logging
 from datetime import timedelta
 from http import HTTPStatus
@@ -86,7 +87,7 @@ class MailAccountViewSet(PassUserMixin, ModelViewSet[MailAccount]):
    @action(methods=["post"], detail=False)
    def test(self, request):
        logger = logging.getLogger("paperless_mail")
-        request.data["name"] = timezone.now().isoformat()
+        request.data["name"] = datetime.datetime.now().isoformat()
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        existing_account = None
Author	SHA1	Message	Date
stumpylog	16f1427b7a	Not bad catches from Copilot, if a little extra secure	2026-08-27 11:37:07 -07:00
stumpylog	8f008a8bf4	feature: add Tantivy full-text fallback adapter for taxonomy candidates This brings users without an embedding backend configured to closer parity with those who do. Reuse the search backend to locate similar documents and use them to provide the LLM with the better suggestion pool to draw from	2026-08-27 09:42:08 -07:00