Merge branch 'main' into claude/resolve-issue-1333-22Y0E

Signed-off-by: JSIV <5049984+JSv4@users.noreply.github.com>

Author: JSv4

CHANGELOG.md

@@ -1,5 +1,9 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
 from django.contrib import admin
-from django.db.models import Count
+from django.db.models import Count, QuerySet
 from guardian.admin import GuardedModelAdmin
 
 from opencontractserver.annotations.models import (
@@ -11,6 +15,9 @@
     Relationship,
 )
 
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+
 
 class ContentModalityFilter(admin.SimpleListFilter):
     """
@@ -21,7 +28,11 @@ class ContentModalityFilter(admin.SimpleListFilter):
     title = "content modality"
     parameter_name = "modality"
 
-    def lookups(self, request, model_admin):
+    def lookups(
+        self,
+        request: HttpRequest,
+        model_admin: admin.ModelAdmin[Any],
+    ) -> tuple[tuple[str, str], ...]:
         return (
             ("text", "TEXT only"),
             ("image", "IMAGE only"),
@@ -31,7 +42,11 @@ def lookups(self, request, model_admin):
             ("empty", "No modalities"),
         )
 
-    def queryset(self, request, queryset):
+    def queryset(
+        self,
+        request: HttpRequest,
+        queryset: QuerySet[Annotation],
+    ) -> QuerySet[Annotation]:
         if self.value() == "text":
             return queryset.filter(content_modalities=["TEXT"])
         if self.value() == "image":
@@ -61,7 +76,7 @@ class AnnotationEmbeddingInline(admin.TabularInline):
     readonly_fields = ("id", "embedder_path", "dimension", "created", "modified")
     extra = 0
 
-    def dimension(self, obj):
+    def dimension(self, obj: Embedding) -> str:
         """Display which vector dimension is populated."""
         if obj.vector_384 is not None:
             return "384"
@@ -73,7 +88,7 @@ def dimension(self, obj):
             return "3072"
         return "Unknown"
 
-    dimension.short_description = "Dimension"
+    dimension.short_description = "Dimension"  # type: ignore[attr-defined]
 
 
 class NoteEmbeddingInline(admin.TabularInline):
@@ -87,7 +102,7 @@ class NoteEmbeddingInline(admin.TabularInline):
     readonly_fields = ("id", "embedder_path", "dimension", "created", "modified")
     extra = 0
 
-    def dimension(self, obj):
+    def dimension(self, obj: Embedding) -> str:
         """Display which vector dimension is populated."""
         if obj.vector_384 is not None:
             return "384"
@@ -99,7 +114,7 @@ def dimension(self, obj):
             return "3072"
         return "Unknown"
 
-    dimension.short_description = "Dimension"
+    dimension.short_description = "Dimension"  # type: ignore[attr-defined]
 
 
 @admin.register(Annotation)
@@ -125,31 +140,31 @@ class AnnotationAdmin(GuardedModelAdmin):
     raw_id_fields = ("annotation_label", "document", "corpus", "analysis", "creator")
     inlines = [AnnotationEmbeddingInline]
 
-    def get_queryset(self, request):
+    def get_queryset(self, request: HttpRequest) -> QuerySet[Any]:
         """
         Override queryset to annotate with embedding count.
         """
         qs = super().get_queryset(request)
         return qs.annotate(total_embeddings=Count("embedding_set", distinct=True))
 
-    def total_embeddings(self, obj):
+    def total_embeddings(self, obj: Annotation) -> int:
         """
         Display the total number of embeddings for this annotation.
         """
-        return obj.total_embeddings
+        return obj.total_embeddings  # type: ignore[attr-defined]
 
-    total_embeddings.admin_order_field = "total_embeddings"
-    total_embeddings.short_description = "Embeddings"
+    total_embeddings.admin_order_field = "total_embeddings"  # type: ignore[attr-defined]
+    total_embeddings.short_description = "Embeddings"  # type: ignore[attr-defined]
 
-    def modality_display(self, obj):
+    def modality_display(self, obj: Annotation) -> str:
         """
         Display content modalities as a formatted string.
         """
         if obj.content_modalities:
             return ", ".join(obj.content_modalities)
         return "-"
 
-    modality_display.short_description = "Modality"
+    modality_display.short_description = "Modality"  # type: ignore[attr-defined]
 
 
 @admin.register(Relationship)
@@ -194,21 +209,21 @@ class NoteAdmin(GuardedModelAdmin):
     raw_id_fields = ("parent", "document", "annotation", "creator")
     inlines = [NoteEmbeddingInline]
 
-    def get_queryset(self, request):
+    def get_queryset(self, request: HttpRequest) -> QuerySet[Any]:
         """
         Override queryset to annotate with embedding count.
         """
         qs = super().get_queryset(request)
         return qs.annotate(total_embeddings=Count("embedding_set", distinct=True))
 
-    def total_embeddings(self, obj):
+    def total_embeddings(self, obj: Note) -> int:
         """
         Display the total number of embeddings for this note.
         """
-        return obj.total_embeddings
+        return obj.total_embeddings  # type: ignore[attr-defined]
 
-    total_embeddings.admin_order_field = "total_embeddings"
-    total_embeddings.short_description = "Embeddings"
+    total_embeddings.admin_order_field = "total_embeddings"  # type: ignore[attr-defined]
+    total_embeddings.short_description = "Embeddings"  # type: ignore[attr-defined]
 
 
 @admin.register(Embedding)
@@ -227,7 +242,7 @@ class EmbeddingAdmin(GuardedModelAdmin):
     search_fields = ["embedder_path", "id"]
     raw_id_fields = ("document", "annotation", "note", "creator")
 
-    def reference_type(self, obj):
+    def reference_type(self, obj: Embedding) -> str:
         """Display what type of object this embedding belongs to."""
         if obj.document_id:
             return f"Document #{obj.document_id}"
@@ -237,11 +252,11 @@ def reference_type(self, obj):
             return f"Note #{obj.note_id}"
         return "Unknown"
 
-    reference_type.short_description = "Referenced Object"
+    reference_type.short_description = "Referenced Object"  # type: ignore[attr-defined]
 
-    def dimension_info(self, obj):
+    def dimension_info(self, obj: Embedding) -> str:
         """Display which vector dimension is populated."""
-        dimensions = []
+        dimensions: list[str] = []
         if obj.vector_384 is not None:
             dimensions.append("384")
         if obj.vector_768 is not None:
@@ -252,4 +267,4 @@ def dimension_info(self, obj):
             dimensions.append("3072")
         return ", ".join(dimensions) if dimensions else "None"
 
-    dimension_info.short_description = "Dimensions"
+    dimension_info.short_description = "Dimensions"  # type: ignore[attr-defined]

opencontractserver/annotations/admin.py

@@ -1,11 +1,13 @@
+from __future__ import annotations
+
 import difflib
 import functools
 import hashlib
 import logging
 import uuid
 
 # Typed representations for the `json` payload
-from typing import Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Union, cast
 
 import django
 from django.contrib.auth import get_user_model
@@ -50,6 +52,9 @@
 )
 from .json_types import MultipageAnnotationJson, SpanAnnotationJson
 
+if TYPE_CHECKING:
+    from django.contrib.auth.models import AbstractBaseUser
+
 User = get_user_model()
 logger = logging.getLogger(__name__)
 
@@ -157,7 +162,7 @@ class Meta:
         ]
 
     # Override save to update modified on save
-    def save(self, *args, **kwargs):
+    def save(self, *args: Any, **kwargs: Any) -> None:
         """On save, update timestamps"""
         if not self.pk:
             self.created = timezone.now()
@@ -376,7 +381,7 @@ def clean(self) -> None:
             )
 
     # Override save to update modified on save
-    def save(self, *args, **kwargs):
+    def save(self, *args: Any, **kwargs: Any) -> None:
         """On save, update timestamps and validate constraints"""
         # Always validate on save (consistent with Annotation model)
         self.clean()
@@ -479,7 +484,7 @@ class Embedding(BaseOCModel):
     created = django.db.models.DateTimeField(default=timezone.now, blank=True)
     modified = django.db.models.DateTimeField(default=timezone.now, blank=True)
 
-    def save(self, *args, **kwargs) -> None:
+    def save(self, *args: Any, **kwargs: Any) -> None:
         """
         Overridden save method:
           - ensures modified timestamp is updated
@@ -583,7 +588,7 @@ class Meta:
         verbose_name = "Embedding"
         verbose_name_plural = "Embeddings"
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"Embedding (ID={self.pk}) [{self.embedder_path or 'Unknown Model'}]"
 
 
@@ -660,20 +665,20 @@ class Meta:
             django.db.models.Index(fields=["created"]),
         ]
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"StructuralAnnotationSet({self.content_hash[:12]}...)"
 
     @property
-    def annotation_count(self):
+    def annotation_count(self) -> int:
         """Get the count of structural annotations in this set."""
         return self.structural_annotations.count()
 
     @property
-    def relationship_count(self):
+    def relationship_count(self) -> int:
         """Get the count of structural relationships in this set."""
         return self.structural_relationships.count()
 
-    def duplicate(self, corpus_id: Optional[int] = None) -> "StructuralAnnotationSet":
+    def duplicate(self, corpus_id: int | None = None) -> StructuralAnnotationSet:
         """
         Create a copy of this set with all its annotations for corpus isolation.
 
@@ -992,15 +997,15 @@ class Annotation(BaseOCModel, HasEmbeddingMixin):
     )
     modified = django.db.models.DateTimeField(default=timezone.now, blank=True)
 
-    def get_embedding_reference_kwargs(self) -> dict:
+    def get_embedding_reference_kwargs(self) -> dict[str, Any]:
         return {"annotation_id": self.pk}
 
     # ---------------------------------------------------------------------
     # Convenience helpers
     # ---------------------------------------------------------------------
 
     @property
-    def typed_json(self) -> "Union[MultipageAnnotationJson, SpanAnnotationJson]":
+    def typed_json(self) -> MultipageAnnotationJson | SpanAnnotationJson:
         """Return `self.json` with a precise static type.
 
         This helper exists purely for IDE / static-analysis benefit. It performs
@@ -1128,7 +1133,7 @@ def clean(self) -> None:  # noqa: C901  (complexity – kept minimal)
     # Persistence
     # ------------------------------------------------------------------
 
-    def save(self, *args, **kwargs):
+    def save(self, *args: Any, **kwargs: Any) -> None:
         """Override save to optionally validate `json` integrity and
         auto-compact the annotation JSON to v2 format.
 
@@ -1258,7 +1263,7 @@ class AnnotationGroupObjectPermission(GroupObjectPermissionBase):
     # enabled = False
 
 
-def calculate_labelset_icon_path(instance, filename):
+def calculate_labelset_icon_path(instance: LabelSet, filename: str) -> str:
     return calc_oc_file_path(
         instance, filename, f"user_{instance.creator.id}/labelsets/icons/{uuid.uuid4()}"
     )
@@ -1410,7 +1415,7 @@ class Note(BaseOCModel, HasEmbeddingMixin):
         10  # store full snapshot every N revisions for fast reconstruction
     )
 
-    def save(self, *args, **kwargs):
+    def save(self, *args: Any, **kwargs: Any) -> None:
         """Override save to automatically create a NoteRevision when `content` changes.
         Set `skip_revision=True` in kwargs to bypass automatic revision creation
         (used internally by `version_up`).
@@ -1438,7 +1443,7 @@ def save(self, *args, **kwargs):
         self.modified = timezone.now()
 
         with transaction.atomic():
-            super_result = super().save(*args, **kwargs)
+            super().save(*args, **kwargs)
 
             # Auto-create a NoteRevision unless explicitly skipped
             if not skip_revision and (
@@ -1480,9 +1485,12 @@ def save(self, *args, **kwargs):
                     ).hexdigest(),
                 )
 
-            return super_result
-
-    def version_up(self, *, new_content: str, author):
+    def version_up(
+        self,
+        *,
+        new_content: str,
+        author: AbstractBaseUser | int,
+    ) -> NoteRevision | None:
         """Utility to bump the note to a new version.
 
         Args:
@@ -1546,7 +1554,7 @@ def version_up(self, *, new_content: str, author):
 
         return revision
 
-    def get_embedding_reference_kwargs(self) -> dict:
+    def get_embedding_reference_kwargs(self) -> dict[str, Any]:
         return {"note_id": self.pk}
 
     class Meta:
@@ -1630,5 +1638,5 @@ class Meta:
         unique_together = ("note", "version")
         ordering = ("note_id", "version")
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"NoteRevision(note_id={self.note_id}, v={self.version})"