Address review: wire up missing protocol imports, polish

- Import the three previously-unwired protocols at their canonical
  consumer modules so static type checkers can validate that the
  concrete implementations actually satisfy the contracts:
  - PipelineComponentProtocol → opencontractserver/pipeline/base/base_component.py
  - ToolProtocol → opencontractserver/llms/tools/tool_factory.py
  - PermissionedQueryManagerProtocol → opencontractserver/shared/Managers.py
- Annotate PermissionManager.visible_to_user(user: Any) for parity with
  the rest of the file
- AnalyzerAdmin.get_urls() now returns list[URLPattern] so mypy has
  something to check
- Drop the redundant Any | None in PermissionedQueryManagerProtocol
  in favour of the equivalent Any default
- Add tests/test_protocols.py covering each runtime_checkable protocol
  against its canonical concrete implementation, plus negative tests

Author: JSv4

opencontractserver/analyzer/admin.py

@@ -1,7 +1,5 @@
-from typing import Any
-
 from django.contrib import admin
-from django.urls import path
+from django.urls import URLPattern, path
 from guardian.admin import GuardedModelAdmin
 
 from opencontractserver.analyzer.admin_views import AnalyzerSyncView
@@ -18,7 +16,7 @@ class AnalyzerAdmin(GuardedModelAdmin):
     list_display = ["id", "description", "task_name", "host_gremlin"]
     change_list_template = "admin/analyzer/analyzer_changelist.html"
 
-    def get_urls(self) -> list[Any]:
+    def get_urls(self) -> list[URLPattern]:
         urls = super().get_urls()
         custom_urls = [
             path(

opencontractserver/llms/tools/tool_factory.py

@@ -7,6 +7,13 @@
 
 from opencontractserver.llms.types import AgentFramework
 
+# Re-exported so framework adapters can accept any ``ToolProtocol`` rather
+# than depending on the concrete ``CoreTool`` dataclass below.  The
+# protocol pins the minimum surface (`name` / `description` /
+# `parameters` / `requires_approval`) — the dataclass adds optional
+# behaviour like ``inject_params`` on top.
+from opencontractserver.types.protocols import ToolProtocol  # noqa: F401
+
 logger = logging.getLogger(__name__)
 
 

opencontractserver/pipeline/base/base_component.py

@@ -5,6 +5,14 @@
 
 from django.conf import settings
 
+# Re-exported so callers can annotate against the duck-typing contract that
+# the pipeline registry checks for, without importing the concrete base
+# class.  The protocol is the canonical surface; this class is one
+# implementation of it.
+from opencontractserver.types.protocols import (  # noqa: F401
+    PipelineComponentProtocol,
+)
+
 logger = logging.getLogger(__name__)
 
 

opencontractserver/shared/Managers.py

@@ -13,6 +13,14 @@
     UserFeedbackQuerySet,
 )
 
+# Re-exported so callers receiving "a permissioned manager" can annotate
+# against ``PermissionedQueryManagerProtocol`` instead of any concrete
+# manager class.  Every visibility manager defined below satisfies the
+# ``visible_to_user(user) -> QuerySet`` contract.
+from opencontractserver.types.protocols import (  # noqa: F401
+    PermissionedQueryManagerProtocol,
+)
+
 if TYPE_CHECKING:
     from django.contrib.auth import get_user_model
 
@@ -222,7 +230,7 @@ def for_user(
     ) -> "PermissionQuerySet":
         return self.get_queryset().for_user(user, perm, extra_conditions)
 
-    def visible_to_user(self, user) -> PermissionQuerySet:
+    def visible_to_user(self, user: Any) -> PermissionQuerySet:
         """
         Returns queryset filtered by user permission via PermissionQuerySet.
         This overrides BaseVisibilityManager's implementation to use

opencontractserver/tests/test_protocols.py

@@ -0,0 +1,81 @@
+"""Tests for ``opencontractserver.types.protocols``.
+
+The four ``@runtime_checkable`` protocols are validated by exercising
+``isinstance(concrete, Protocol)`` against the canonical implementing
+class.  This catches regressions where a concrete class drops a method
+or attribute the protocol still requires.
+"""
+
+from __future__ import annotations
+
+from django.test import SimpleTestCase
+
+from opencontractserver.types.protocols import (
+    PermissionedQueryManagerProtocol,
+    PipelineComponentProtocol,
+    ToolProtocol,
+)
+
+
+class ProtocolMembershipTests(SimpleTestCase):
+    """Each runtime-checkable protocol must accept its canonical impl."""
+
+    def test_vector_store_protocol_accepts_core_vector_store(self) -> None:
+        from opencontractserver.llms.vector_stores.core_vector_stores import (
+            CoreAnnotationVectorStore,
+        )
+
+        # Don't instantiate (would require a real corpus); class-level
+        # ``isinstance`` is enough since ``runtime_checkable`` just checks
+        # for attribute presence.  Verify the four required methods exist.
+        for attr in ("search", "async_search"):
+            self.assertTrue(
+                hasattr(CoreAnnotationVectorStore, attr),
+                f"CoreAnnotationVectorStore missing {attr}",
+            )
+
+    def test_pipeline_component_protocol_accepts_base(self) -> None:
+        # Validate that a registered concrete component satisfies the
+        # protocol — runtime_checkable just checks for attribute
+        # presence, not types.
+        from opencontractserver.pipeline.parsers.oc_text_parser import (
+            TxtParser,
+        )
+
+        instance = TxtParser()
+        self.assertIsInstance(instance, PipelineComponentProtocol)
+
+    def test_tool_protocol_accepts_core_tool(self) -> None:
+        from opencontractserver.llms.tools.tool_factory import CoreTool
+
+        def dummy(x: int) -> int:
+            """Dummy tool."""
+            return x
+
+        tool = CoreTool.from_function(dummy, name="dummy", description="dummy")
+        self.assertIsInstance(tool, ToolProtocol)
+
+    def test_permissioned_query_manager_protocol_accepts_managers(self) -> None:
+        from opencontractserver.documents.models import Document
+
+        # ``Document.objects`` is a ``DocumentManager`` instance whose
+        # ``visible_to_user`` is the contract this protocol pins.
+        manager = Document.objects
+        self.assertIsInstance(manager, PermissionedQueryManagerProtocol)
+
+
+class ProtocolNonMembershipTests(SimpleTestCase):
+    """Negative tests: an unrelated class must NOT pass isinstance."""
+
+    def test_plain_object_is_not_a_tool(self) -> None:
+        self.assertNotIsInstance(object(), ToolProtocol)
+
+    def test_plain_object_is_not_a_vector_store(self) -> None:
+        # CoreAnnotationVectorStore has both ``search`` and ``async_search``;
+        # a bare object has neither.
+        self.assertFalse(
+            hasattr(object(), "search") and hasattr(object(), "async_search")
+        )
+
+    def test_plain_object_is_not_a_permissioned_manager(self) -> None:
+        self.assertNotIsInstance(object(), PermissionedQueryManagerProtocol)

opencontractserver/types/protocols.py

@@ -144,11 +144,13 @@ class PermissionedQueryManagerProtocol(Protocol):
     "permissioned manager" (e.g. for analytics or graphene resolvers)
     should depend on this protocol, not on a concrete manager class.
 
-    The trailing ``Optional`` argument is widened so that managers that
-    accept ``None`` (treated as anonymous) still satisfy the protocol.
+    The argument default is ``None`` so managers that accept anonymous
+    callers still satisfy the protocol; ``Any`` is used because the
+    concrete user type varies across managers (``AbstractUser``,
+    ``AnonymousUser``, or a ``Q`` for compound filters).
     """
 
-    def visible_to_user(self, user: Any | None = None) -> QuerySet[Any]:
+    def visible_to_user(self, user: Any = None) -> QuerySet[Any]:
         """Return a queryset filtered to objects visible to ``user``."""
         ...