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:
Trenton H authored and GitHub committed 2026-08-14 15:51:34 -07:00
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
+225 -18
View File
@@ -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 = {