mirror of
https://github.com/paperless-ngx/paperless-ngx.git
synced 2026-11-21 13:02:40 +00:00
Enhancement: prefer existing tags, types, correspondents, and storage paths in AI suggestions (#13676)
AI Suggestions previously invented near-duplicate metadata because the classification prompt had no knowledge of the installation's own taxonomy. This surfaces a small, ranked, permission-filtered set of existing tags/document types/correspondents/storage paths - drawn from the document's RAG neighbors plus its own already-assigned metadata - so the model prefers reusing what already exists. The LLM response schema now returns existing_ids (IDs of reused candidates) separately from new_names (genuinely new suggestions). Only new_names goes through localization and fuzzy name-matching; existing_ids is resolved deterministically and never touched by the localization pass, so exact matches can no longer be silently corrupted by translation.
This commit is contained in:
1 parent
3322c92837
commit
0e5fbc973a
16 files changed
+2639
-520
No files matched your search
@@ -22,6 +22,7 @@ from documents.models import StoragePath
|
||||
from documents.models import Tag
|
||||
from documents.permissions import permitted_document_ids
|
||||
from documents.permissions import permitted_object_ids
|
||||
from documents.permissions import restrict_queryset_to_visible
|
||||
from documents.serialisers import _get_viewable_duplicates
|
||||
from documents.tests.factories import CorrespondentFactory
|
||||
from documents.tests.factories import DocumentFactory
|
||||
@@ -736,7 +737,7 @@ class TestBulkEditObjectsTagDescendantPartialPermission:
|
||||
NOTE: this uses ``set_permissions`` (owner reassignment) rather than
|
||||
``delete`` as the operation, because Tag.tn_parent (django-treenode)
|
||||
cascades deletes to descendants at the database/ORM level regardless
|
||||
of which tags the view resolved into ``objs`` -- a delete-based test
|
||||
of which tags the view resolved into ``objs`` - a delete-based test
|
||||
would pass/fail based on FK cascade behavior, not on whether the
|
||||
descendant-expansion logic itself respected per-object permissions.
|
||||
"""
|
||||
@@ -783,3 +784,97 @@ class TestBulkEditObjectsTagDescendantPartialPermission:
|
||||
assert parent.owner == requester
|
||||
assert permitted_child.owner == requester
|
||||
assert unpermitted_child.owner == owner
|
||||
|
||||
|
||||
@pytest.mark.django_db
|
||||
class TestRestrictQuerysetToVisible:
|
||||
"""restrict_queryset_to_visible() returns its queryset argument
|
||||
unchanged only for "no restriction at all", so the cases that may do
|
||||
that have to be kept narrow."""
|
||||
|
||||
def test_no_user_means_no_restriction(self) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- No user at all (a system-triggered call)
|
||||
WHEN:
|
||||
- restrict_queryset_to_visible() is called
|
||||
THEN:
|
||||
- The queryset is returned unfiltered, rather than
|
||||
permitted_object_ids(None, ...)'s narrower "unowned rows only"
|
||||
"""
|
||||
owner = User.objects.create_user(username="vis_none_owner")
|
||||
tag = TagFactory(owner=owner)
|
||||
|
||||
visible = restrict_queryset_to_visible(Tag.objects.all(), None, "view_tag")
|
||||
|
||||
assert tag.pk in visible.values_list("pk", flat=True)
|
||||
|
||||
def test_active_superuser_means_no_restriction(self) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- An active superuser
|
||||
WHEN:
|
||||
- restrict_queryset_to_visible() is called
|
||||
THEN:
|
||||
- The queryset is returned unfiltered, skipping the permission
|
||||
lookup entirely
|
||||
"""
|
||||
superuser = User.objects.create_superuser(username="vis_active_super")
|
||||
owner = User.objects.create_user(username="vis_active_super_owner")
|
||||
tag = TagFactory(owner=owner)
|
||||
|
||||
visible = restrict_queryset_to_visible(
|
||||
Tag.objects.all(),
|
||||
superuser,
|
||||
"view_tag",
|
||||
)
|
||||
|
||||
assert tag.pk in visible.values_list("pk", flat=True)
|
||||
|
||||
def test_inactive_superuser_is_denied_not_unrestricted(self) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- A deactivated superuser
|
||||
WHEN:
|
||||
- restrict_queryset_to_visible() is called
|
||||
THEN:
|
||||
- No rows are visible, never the whole unrestricted queryset -
|
||||
deactivation has to win over the superuser shortcut, matching
|
||||
permitted_object_ids's own ordering
|
||||
"""
|
||||
user = User.objects.create_user(
|
||||
username="vis_inactive_super",
|
||||
is_active=False,
|
||||
is_superuser=True,
|
||||
)
|
||||
TagFactory(owner=None)
|
||||
TagFactory(owner=user)
|
||||
|
||||
visible = restrict_queryset_to_visible(Tag.objects.all(), user, "view_tag")
|
||||
|
||||
assert not visible.exists()
|
||||
|
||||
def test_regular_user_gets_permitted_ids(self) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- An ordinary active user and a tag owned by someone else
|
||||
WHEN:
|
||||
- restrict_queryset_to_visible() is called
|
||||
THEN:
|
||||
- Only the rows permitted_object_ids() reports are visible
|
||||
"""
|
||||
user = User.objects.create_user(username="vis_regular")
|
||||
other = User.objects.create_user(username="vis_regular_other")
|
||||
own = TagFactory(owner=user)
|
||||
hidden = TagFactory(owner=other)
|
||||
|
||||
visible_ids = set(
|
||||
restrict_queryset_to_visible(
|
||||
Tag.objects.all(),
|
||||
user,
|
||||
"view_tag",
|
||||
).values_list("pk", flat=True),
|
||||
)
|
||||
|
||||
assert own.pk in visible_ids
|
||||
assert hidden.pk not in visible_ids
|
||||
@@ -352,20 +352,95 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
|
||||
mock_refresh_cache,
|
||||
mock_get_cache,
|
||||
) -> None:
|
||||
mock_get_cache.return_value = MagicMock(suggestions={"tags": ["tag1", "tag2"]})
|
||||
"""
|
||||
GIVEN:
|
||||
- A cached LLM classification holding the raw existing_ids/
|
||||
new_names choices (never resolved object ids)
|
||||
WHEN:
|
||||
- ai_suggestions is requested
|
||||
THEN:
|
||||
- The cached choices are resolved into ids for this request
|
||||
(not returned verbatim from the cache) and the cache's TTL is
|
||||
refreshed
|
||||
"""
|
||||
mock_get_cache.return_value = MagicMock(
|
||||
suggestions={
|
||||
"title": "Cached Title",
|
||||
"tags": {"existing_ids": [self.tag1.pk], "new_names": []},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
},
|
||||
)
|
||||
|
||||
self.client.force_login(user=self.user)
|
||||
response = self.client.get(
|
||||
f"/api/documents/{self.document.pk}/ai_suggestions/",
|
||||
)
|
||||
self.assertEqual(response.status_code, status.HTTP_200_OK)
|
||||
self.assertEqual(response.json(), {"tags": ["tag1", "tag2"]})
|
||||
self.assertEqual(response.json()["title"], "Cached Title")
|
||||
self.assertEqual(response.json()["tags"], [self.tag1.pk])
|
||||
mock_get_cache.assert_called_once_with(
|
||||
self.document.pk,
|
||||
backend="mock_backend",
|
||||
)
|
||||
mock_refresh_cache.assert_called_once_with(self.document.pk)
|
||||
|
||||
@patch("documents.views.get_llm_suggestion_cache")
|
||||
@patch("documents.views.refresh_suggestions_cache")
|
||||
@override_settings(
|
||||
AI_ENABLED=True,
|
||||
LLM_BACKEND="mock_backend",
|
||||
)
|
||||
def test_ai_suggestions_cache_hit_re_filters_for_narrower_requester(
|
||||
self,
|
||||
mock_refresh_cache,
|
||||
mock_get_cache,
|
||||
) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- A cached LLM classification whose existing_ids include a tag
|
||||
only visible to a broader-visibility user (e.g. the requester
|
||||
who originally generated it)
|
||||
- A second, non-superuser requester who may change the document
|
||||
but has no permission to view that tag
|
||||
WHEN:
|
||||
- ai_suggestions is requested by the second requester and the
|
||||
cache is hit
|
||||
THEN:
|
||||
- The cache hit still runs permission filtering fresh for this
|
||||
requester; the invisible tag id does not leak into either the
|
||||
matched or suggested tags
|
||||
"""
|
||||
tag_owner = User.objects.create_user(username="cache_tag_owner")
|
||||
invisible_tag = Tag.objects.create(name="cache_restricted", owner=tag_owner)
|
||||
requester = User.objects.create_user(username="cache_requester")
|
||||
requester.user_permissions.add(
|
||||
*Permission.objects.filter(
|
||||
codename__in=["view_document", "change_document", "view_tag"],
|
||||
),
|
||||
)
|
||||
mock_get_cache.return_value = MagicMock(
|
||||
suggestions={
|
||||
"title": "Untitled",
|
||||
"tags": {"existing_ids": [invisible_tag.pk], "new_names": []},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
},
|
||||
)
|
||||
|
||||
self.client.force_login(user=requester)
|
||||
response = self.client.get(
|
||||
f"/api/documents/{self.document.pk}/ai_suggestions/",
|
||||
)
|
||||
|
||||
self.assertEqual(response.status_code, status.HTTP_200_OK)
|
||||
self.assertEqual(response.json()["tags"], [])
|
||||
self.assertEqual(response.json()["suggested_tags"], [])
|
||||
|
||||
@patch("documents.views.get_ai_document_classification")
|
||||
@override_settings(
|
||||
AI_ENABLED=True,
|
||||
@@ -377,10 +452,16 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
|
||||
) -> None:
|
||||
mock_get_ai_classification.return_value = {
|
||||
"title": "AI Title",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"correspondents": ["correspondent1"],
|
||||
"document_types": ["type1"],
|
||||
"storage_paths": ["path1"],
|
||||
"tags": {"existing_ids": [self.tag1.pk], "new_names": ["tag2"]},
|
||||
"correspondents": {
|
||||
"existing_ids": [self.correspondent1.pk],
|
||||
"new_names": [],
|
||||
},
|
||||
"document_types": {
|
||||
"existing_ids": [self.document_type1.pk],
|
||||
"new_names": [],
|
||||
},
|
||||
"storage_paths": {"existing_ids": [self.path1.pk], "new_names": []},
|
||||
"dates": ["2023-01-01"],
|
||||
}
|
||||
|
||||
@@ -422,10 +503,10 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
|
||||
UiSettings.objects.create(user=self.user, settings={"language": "de-de"})
|
||||
mock_get_ai_classification.return_value = {
|
||||
"title": "KI Title",
|
||||
"tags": [],
|
||||
"correspondents": [],
|
||||
"document_types": [],
|
||||
"storage_paths": [],
|
||||
"tags": {"existing_ids": [], "new_names": []},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
}
|
||||
|
||||
@@ -461,10 +542,10 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
|
||||
UiSettings.objects.create(user=self.user, settings={"language": "de-de"})
|
||||
mock_get_ai_classification.return_value = {
|
||||
"title": "Titre IA",
|
||||
"tags": [],
|
||||
"correspondents": [],
|
||||
"document_types": [],
|
||||
"storage_paths": [],
|
||||
"tags": {"existing_ids": [], "new_names": []},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
}
|
||||
|
||||
@@ -502,10 +583,10 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
|
||||
either yields a cache miss instead of a stale hit."""
|
||||
mock_get_ai_classification.return_value = {
|
||||
"title": "Answer A",
|
||||
"tags": [],
|
||||
"correspondents": [],
|
||||
"document_types": [],
|
||||
"storage_paths": [],
|
||||
"tags": {"existing_ids": [], "new_names": []},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
}
|
||||
|
||||
@@ -579,6 +660,132 @@ class TestAISuggestions(DirectoriesMixin, TestCase):
|
||||
get_llm_suggestion_cache(self.document.pk, backend="openai-like"),
|
||||
)
|
||||
|
||||
@patch("documents.views.get_ai_document_classification")
|
||||
@override_settings(
|
||||
AI_ENABLED=True,
|
||||
LLM_BACKEND="mock_backend",
|
||||
)
|
||||
def test_ai_suggestions_combines_existing_ids_and_new_names(
|
||||
self,
|
||||
mock_get_ai_classification,
|
||||
) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- AI classification returns a taxonomy choice with both an
|
||||
existing tag id and a new tag name not present in the database
|
||||
WHEN:
|
||||
- ai_suggestions is requested
|
||||
THEN:
|
||||
- the existing id is resolved into the matched tags list
|
||||
- the new name is fuzzy-matched, and since it doesn't match any
|
||||
existing tag, it is surfaced as a suggested tag
|
||||
"""
|
||||
mock_get_ai_classification.return_value = {
|
||||
"title": "Lab Report",
|
||||
"tags": {"existing_ids": [self.tag1.pk], "new_names": ["Follow-up"]},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
}
|
||||
|
||||
self.client.force_login(user=self.user)
|
||||
response = self.client.get(
|
||||
f"/api/documents/{self.document.pk}/ai_suggestions/",
|
||||
)
|
||||
|
||||
self.assertEqual(response.status_code, status.HTTP_200_OK)
|
||||
self.assertEqual(response.json()["tags"], [self.tag1.pk])
|
||||
self.assertEqual(response.json()["suggested_tags"], ["Follow-up"])
|
||||
|
||||
@patch("documents.views.get_ai_document_classification")
|
||||
@override_settings(
|
||||
AI_ENABLED=True,
|
||||
LLM_BACKEND="mock_backend",
|
||||
)
|
||||
def test_ai_suggestions_deduplicates_id_matched_via_both_paths(
|
||||
self,
|
||||
mock_get_ai_classification,
|
||||
) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- AI classification returns the same tag both as an existing_id
|
||||
and as a new_name that fuzzy-matches that same tag
|
||||
WHEN:
|
||||
- ai_suggestions is requested
|
||||
THEN:
|
||||
- The tag's id appears exactly once in the response, not twice
|
||||
"""
|
||||
mock_get_ai_classification.return_value = {
|
||||
"title": "Lab Report",
|
||||
"tags": {
|
||||
"existing_ids": [self.tag1.pk],
|
||||
"new_names": [self.tag1.name],
|
||||
},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
}
|
||||
|
||||
self.client.force_login(user=self.user)
|
||||
response = self.client.get(
|
||||
f"/api/documents/{self.document.pk}/ai_suggestions/",
|
||||
)
|
||||
|
||||
self.assertEqual(response.status_code, status.HTTP_200_OK)
|
||||
self.assertEqual(response.json()["tags"], [self.tag1.pk])
|
||||
self.assertEqual(response.json()["suggested_tags"], [])
|
||||
|
||||
@patch("documents.views.get_ai_document_classification")
|
||||
@override_settings(
|
||||
AI_ENABLED=True,
|
||||
LLM_BACKEND="mock_backend",
|
||||
)
|
||||
def test_ai_suggestions_existing_id_not_visible_falls_through_to_suggested(
|
||||
self,
|
||||
mock_get_ai_classification,
|
||||
) -> None:
|
||||
"""
|
||||
GIVEN:
|
||||
- A non-superuser who may change the document but has no
|
||||
permission to view a tag owned by somebody else
|
||||
- AI classification returns that tag's id in existing_ids (e.g.
|
||||
from a cached response generated for a broader-visibility user)
|
||||
WHEN:
|
||||
- ai_suggestions is requested by that user
|
||||
THEN:
|
||||
- the invisible id is silently dropped by resolve_tag_ids, so
|
||||
permission filtering survives the full request path
|
||||
- it does not appear in either the matched or suggested tags
|
||||
"""
|
||||
tag_owner = User.objects.create_user(username="tagowner")
|
||||
invisible_tag = Tag.objects.create(name="restricted", owner=tag_owner)
|
||||
requester = User.objects.create_user(username="requester")
|
||||
requester.user_permissions.add(
|
||||
*Permission.objects.filter(
|
||||
codename__in=["view_document", "change_document", "view_tag"],
|
||||
),
|
||||
)
|
||||
|
||||
mock_get_ai_classification.return_value = {
|
||||
"title": "Untitled",
|
||||
"tags": {"existing_ids": [invisible_tag.pk], "new_names": []},
|
||||
"correspondents": {"existing_ids": [], "new_names": []},
|
||||
"document_types": {"existing_ids": [], "new_names": []},
|
||||
"storage_paths": {"existing_ids": [], "new_names": []},
|
||||
"dates": [],
|
||||
}
|
||||
|
||||
self.client.force_login(user=requester)
|
||||
response = self.client.get(
|
||||
f"/api/documents/{self.document.pk}/ai_suggestions/",
|
||||
)
|
||||
|
||||
self.assertEqual(response.status_code, status.HTTP_200_OK)
|
||||
self.assertEqual(response.json()["tags"], [])
|
||||
self.assertEqual(response.json()["suggested_tags"], [])
|
||||
|
||||
def test_invalidate_suggestions_cache(self) -> None:
|
||||
self.client.force_login(user=self.user)
|
||||
suggestions = {
|
||||
|
||||
Reference in new issue
Block a user