netbox-data-import 2.1.0__tar.gz → 2.2.0__tar.gz

{netbox_data_import-2.1.0 → netbox_data_import-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-data-import
-Version: 2.1.0
+Version: 2.2.0
 Summary: NetBox plugin for importing data from external DCIM systems
 Author: Marcin Zieba
 License-Expression: Apache-2.0

{netbox_data_import-2.1.0 → netbox_data_import-2.2.0}/netbox_data_import/__init__.py

@@ -4,7 +4,7 @@ from typing import Any
 
 from netbox.plugins import PluginConfig
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 
 class NetBoxDataImportConfig(PluginConfig):
@@ -40,10 +40,10 @@ class NetBoxDataImportConfig(PluginConfig):
             raise ImproperlyConfigured(f"Plugin {cls.__module__} has an invalid configuration: {exc}") from exc
 
     def ready(self):
-        """Import the jobs module, which NetBox does not load, so its @system_job registration runs."""
+        """Import the modules NetBox does not load, so their job and task registrations run."""
         super().ready()
 
-        from . import jobs
+        from . import jobs, termination_proposal
 
 
 config = NetBoxDataImportConfig

{netbox_data_import-2.1.0 → netbox_data_import-2.2.0}/netbox_data_import/api/serializers.py

@@ -19,6 +19,8 @@ from ..models import (
     ColumnTransformRule,
     SourceResolution,
     ImportExecution,
+    InferenceBackend,
+    ResolutionProposal,
     validate_adapter_target_module,
     validate_contact_candidate_resolution,
     validate_section_applicability,
@@ -278,3 +280,78 @@ class ImportExecutionSerializer(serializers.ModelSerializer):
             "failure_detail",
         ]
         read_only_fields = fields
+
+
+class ResolutionProposalSerializer(serializers.ModelSerializer):
+    """Read-only serializer for the Resolution Proposal audit record."""
+
+    class Meta:
+        model = ResolutionProposal
+        fields = [
+            "id",
+            "profile",
+            "task_type",
+            "field_key",
+            "status",
+            "source_evidence",
+            "resolved_device_type",
+            "resolved_device_id",
+            "prompt_version",
+            "response_schema_version",
+            "candidate_snapshot",
+            "requested_by",
+            "created",
+            "last_updated",
+            "outcome",
+            "selected_candidate_id",
+            "selected_object_type",
+            "selected_object_id",
+            "explanation",
+            "backend_metadata",
+            "response_diagnostic",
+            "failure_reason",
+            "decision",
+            "decided_by",
+            "decided_at",
+            "written_resolution",
+        ]
+        read_only_fields = fields
+
+
+class ResolutionProposalHistorySerializer(serializers.ModelSerializer):
+    """Serialize one attempt summary for profile-scoped field history."""
+
+    class Meta:
+        model = ResolutionProposal
+        fields = ["id", "created", "status", "outcome", "decision", "failure_reason"]
+        read_only_fields = fields
+
+
+class InferenceBackendSerializer(NetBoxModelSerializer):
+    """Serialize one Inference Backend row, without its credential reference.
+
+    NetBox resolves this class by model name to freeze a delete event payload.
+    """
+
+    class Meta:
+        model = InferenceBackend
+        fields = [
+            "id",
+            "url",
+            "display",
+            "backend_key",
+            "display_name",
+            "adapter_type",
+            "api_root",
+            "model",
+            "authentication",
+            "response_mode",
+            "connect_timeout",
+            "read_timeout",
+            "enabled",
+            "tags",
+            "custom_fields",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ["id", "url", "display", "backend_key", "display_name", "enabled"]

{netbox_data_import-2.1.0 → netbox_data_import-2.2.0}/netbox_data_import/api/urls.py

@@ -2,6 +2,7 @@
 # Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
 """URL router for the data-import plugin API."""
 
+from django.urls import path
 from netbox.api.routers import NetBoxRouter
 
 from .views import (
@@ -13,6 +14,9 @@ from .views import (
     ColumnTransformRuleViewSet,
     SourceResolutionViewSet,
     ImportExecutionViewSet,
+    InferenceBackendViewSet,
+    ResolutionProposalHistoryViewSet,
+    ResolutionProposalViewSet,
 )
 
 router = NetBoxRouter()
@@ -24,6 +28,15 @@ router.register("ignored-devices", IgnoredDeviceViewSet)
 router.register("column-transforms", ColumnTransformRuleViewSet)
 router.register("source-resolutions", SourceResolutionViewSet)
 router.register("executions", ImportExecutionViewSet)
+router.register("ai-backends", InferenceBackendViewSet)
+router.register("resolution-proposals", ResolutionProposalViewSet)
 
 app_name = "netbox_data_import"
-urlpatterns = router.urls
+urlpatterns = [
+    path(
+        "resolution-proposal-history/",
+        ResolutionProposalHistoryViewSet.as_view({"get": "list"}),
+        name="resolutionproposalhistory-list",
+    ),
+    *router.urls,
+]

{netbox_data_import-2.1.0 → netbox_data_import-2.2.0}/netbox_data_import/api/views.py

@@ -3,10 +3,12 @@
 """DRF viewsets for the data-import plugin API."""
 
 from django.http import Http404
-from netbox.api.viewsets import NetBoxModelViewSet
-from rest_framework import viewsets, permissions
+from netbox.api.viewsets import NetBoxModelViewSet, NetBoxReadOnlyModelViewSet
+from rest_framework import mixins, permissions, viewsets
+from rest_framework.exceptions import ValidationError
 from rest_framework.permissions import DjangoModelPermissions
 
+from ..field_keys import SELECT_TERMINATION_TASK, parse_termination_field_key
 from ..models import (
     locked_profile_policy,
     locked_resolution_policy,
@@ -18,6 +20,8 @@ from ..models import (
     ColumnTransformRule,
     SourceResolution,
     ImportExecution,
+    InferenceBackend,
+    ResolutionProposal,
 )
 from .serializers import (
     ImportProfileSerializer,
@@ -28,6 +32,9 @@ from .serializers import (
     ColumnTransformRuleSerializer,
     SourceResolutionSerializer,
     ImportExecutionSerializer,
+    InferenceBackendSerializer,
+    ResolutionProposalHistorySerializer,
+    ResolutionProposalSerializer,
 )
 
 
@@ -56,7 +63,23 @@ class ImportProfileViewSet(NetBoxModelViewSet):
     serializer_class = ImportProfileSerializer
 
 
-class _PluginModelViewSet(viewsets.ModelViewSet):
+class _ProfileScopedQuerySetMixin(viewsets.GenericViewSet):
+    """Restrict profile-owned rows and validate their optional profile filter."""
+
+    def get_queryset(self):
+        """Return viewable rows, filtered by a valid profile ID when supplied."""
+        qs = super().get_queryset().restrict(self.request.user, "view")
+        profile_id = self.request.query_params.get("profile_id")
+        if profile_id is not None:
+            try:
+                profile_id = int(profile_id)
+            except (TypeError, ValueError) as exc:
+                raise ValidationError({"profile_id": "Enter a whole number."}) from exc
+            qs = qs.filter(profile_id=profile_id)
+        return qs
+
+
+class _PluginModelViewSet(_ProfileScopedQuerySetMixin, viewsets.ModelViewSet):
     """Base class for plain-model viewsets in this plugin."""
 
     permission_classes = [permissions.IsAuthenticated, DjangoModelPermissionsWithView]
@@ -68,14 +91,6 @@ class ColumnMappingViewSet(_PluginModelViewSet):
     queryset = ColumnMapping.objects.select_related("profile")
     serializer_class = ColumnMappingSerializer
 
-    def get_queryset(self):
-        """Filter by profile_id query param if provided."""
-        qs = super().get_queryset()
-        profile_id = self.request.query_params.get("profile_id")
-        if profile_id:
-            qs = qs.filter(profile_id=profile_id)
-        return qs
-
 
 class ClassRoleMappingViewSet(_PluginModelViewSet):
     """CRUD viewset for ClassRoleMapping."""
@@ -83,14 +98,6 @@ class ClassRoleMappingViewSet(_PluginModelViewSet):
     queryset = ClassRoleMapping.objects.select_related("profile", "rack_type")
     serializer_class = ClassRoleMappingSerializer
 
-    def get_queryset(self):
-        """Filter by profile_id query param if provided."""
-        qs = super().get_queryset()
-        profile_id = self.request.query_params.get("profile_id")
-        if profile_id:
-            qs = qs.filter(profile_id=profile_id)
-        return qs
-
 
 class DeviceTypeMappingViewSet(_PluginModelViewSet):
     """CRUD viewset for DeviceTypeMapping."""
@@ -98,14 +105,6 @@ class DeviceTypeMappingViewSet(_PluginModelViewSet):
     queryset = DeviceTypeMapping.objects.select_related("profile")
     serializer_class = DeviceTypeMappingSerializer
 
-    def get_queryset(self):
-        """Filter by profile_id query param if provided."""
-        qs = super().get_queryset()
-        profile_id = self.request.query_params.get("profile_id")
-        if profile_id:
-            qs = qs.filter(profile_id=profile_id)
-        return qs
-
 
 class IgnoredDeviceViewSet(_PluginModelViewSet):
     """CRUD viewset for IgnoredDevice."""
@@ -113,14 +112,6 @@ class IgnoredDeviceViewSet(_PluginModelViewSet):
     queryset = IgnoredDevice.objects.select_related("profile")
     serializer_class = IgnoredDeviceSerializer
 
-    def get_queryset(self):
-        """Filter by profile_id query param if provided."""
-        qs = super().get_queryset()
-        profile_id = self.request.query_params.get("profile_id")
-        if profile_id:
-            qs = qs.filter(profile_id=profile_id)
-        return qs
-
 
 class ColumnTransformRuleViewSet(_PluginModelViewSet):
     """CRUD viewset for ColumnTransformRule."""
@@ -128,14 +119,6 @@ class ColumnTransformRuleViewSet(_PluginModelViewSet):
     queryset = ColumnTransformRule.objects.select_related("profile")
     serializer_class = ColumnTransformRuleSerializer
 
-    def get_queryset(self):
-        """Filter by profile_id query param if provided."""
-        qs = super().get_queryset()
-        profile_id = self.request.query_params.get("profile_id")
-        if profile_id:
-            qs = qs.filter(profile_id=profile_id)
-        return qs
-
 
 def _revalidate_against_the_stored_row(serializer):
     """Read the resolution again and check the request against the row as it now stands.
@@ -184,26 +167,70 @@ class SourceResolutionViewSet(_PluginModelViewSet):
         except (SourceResolution.DoesNotExist, ImportProfile.DoesNotExist):
             raise Http404 from None
 
-    def get_queryset(self):
-        """Filter by profile_id query param if provided."""
-        qs = super().get_queryset()
-        profile_id = self.request.query_params.get("profile_id")
-        if profile_id:
-            qs = qs.filter(profile_id=profile_id)
-        return qs
-
 
-class ImportExecutionViewSet(viewsets.ReadOnlyModelViewSet):
+class ImportExecutionViewSet(_ProfileScopedQuerySetMixin, viewsets.ReadOnlyModelViewSet):
     """Read-only viewset for the Import Execution audit history."""
 
     queryset = ImportExecution.objects.select_related("profile")
     serializer_class = ImportExecutionSerializer
     permission_classes = [permissions.IsAuthenticated, DjangoModelPermissionsWithView]
 
+
+class ResolutionProposalViewSet(_ProfileScopedQuerySetMixin, viewsets.ReadOnlyModelViewSet):
+    """Read-only viewset for Resolution Proposal history."""
+
+    queryset = ResolutionProposal.objects.select_related("profile")
+    serializer_class = ResolutionProposalSerializer
+    permission_classes = [permissions.IsAuthenticated, DjangoModelPermissionsWithView]
+
     def get_queryset(self):
-        """Filter by profile_id query param if provided."""
-        qs = super().get_queryset()
-        profile_id = self.request.query_params.get("profile_id")
-        if profile_id:
-            qs = qs.filter(profile_id=profile_id)
-        return qs
+        """Return proposals only for profiles that the actor can view."""
+        profile_scope = ImportProfile.objects.restrict(self.request.user, "view")
+        return super().get_queryset().filter(profile__in=profile_scope)
+
+
+class ResolutionProposalHistoryViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
+    """Read one field's complete paginated history with workspace permissions."""
+
+    queryset = ResolutionProposal.objects.none()
+    serializer_class = ResolutionProposalHistorySerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_queryset(self):
+        """Return one profile field's history when the actor can view that profile."""
+        profile_values = self.request.query_params.getlist("profile_id")
+        field_values = self.request.query_params.getlist("field_key")
+        if len(profile_values) != 1 or not profile_values[0]:
+            raise ValidationError({"profile_id": "Provide one whole-number profile ID."})
+        if len(field_values) != 1 or not field_values[0]:
+            raise ValidationError({"field_key": "Provide one canonical termination field key."})
+        try:
+            profile_id = int(profile_values[0])
+        except (TypeError, ValueError) as exc:
+            raise ValidationError({"profile_id": "Provide one whole-number profile ID."}) from exc
+        try:
+            parse_termination_field_key(field_values[0])
+        except ValueError as exc:
+            raise ValidationError({"field_key": "Provide one canonical termination field key."}) from exc
+        if not ImportProfile.objects.restrict(self.request.user, "view").filter(pk=profile_id).exists():
+            raise Http404
+        return (
+            ResolutionProposal.objects.filter(
+                profile_id=profile_id,
+                task_type=SELECT_TERMINATION_TASK,
+                field_key=field_values[0],
+            )
+            .select_related("profile")
+            .order_by("-created", "-pk")
+        )
+
+
+class InferenceBackendViewSet(NetBoxReadOnlyModelViewSet):
+    """Read-only viewset for Inference Backend rows.
+
+    Read-only on purpose: a backend row carries the destination NetBox itself calls, and the UI form
+    is the one place that validates the `api_root` trust boundary against the allowlist.
+    """
+
+    queryset = InferenceBackend.objects.prefetch_related("tags")
+    serializer_class = InferenceBackendSerializer

{netbox_data_import-2.1.0 → netbox_data_import-2.2.0}/netbox_data_import/cable_target.py

@@ -303,7 +303,7 @@ def _source_record(trace, segment_index: int) -> dict:
     }
 
 
-def _visible_devices(netbox_reader, names) -> dict[str, list]:
+def _visible_devices(netbox_reader, names, *, _lock_rows=False) -> dict[str, list]:
     """Return the visible Devices at the import target, grouped by comparison name."""
     from django.db.models import Q
 
@@ -313,6 +313,8 @@ def _visible_devices(netbox_reader, names) -> dict[str, list]:
     devices = netbox_reader.devices()
     if netbox_reader.site is not None:
         devices = devices.filter(site=netbox_reader.site)
+    if _lock_rows:
+        devices = devices.order_by("pk").select_for_update(of=("self",))
     lookup = Q()
     for name in sorted(wanted):
         lookup |= Q(name__iexact=name)
@@ -324,6 +326,20 @@ def _visible_devices(netbox_reader, names) -> dict[str, list]:
     return grouped
 
 
+def resolved_device_for(field_key: str, netbox_reader, *, _lock_rows=False):
+    """Return the one visible Device a termination field key names, or None when it names no single one.
+
+    A proposal freezes this reference and revalidates it, so the retrieval and the freshness check
+    have to agree on what "the resolved Device" means.
+    """
+    device_name = parse_termination_field_key(field_key)["device"]
+    devices = _visible_devices(netbox_reader, [device_name], _lock_rows=_lock_rows).get(identity_text(device_name), [])
+    return devices[0] if len(devices) == 1 else None
+
+
+_RESOLVED_DEVICE_UNSET = object()
+
+
 def eligible_terminations(
     field_key: str,
     netbox_reader,
@@ -331,6 +347,8 @@ def eligible_terminations(
     profile,
     search: str = "",
     limit: int = ELIGIBLE_TERMINATION_LIMIT,
+    _resolved_device=_RESOLVED_DEVICE_UNSET,
+    _lock_rows: bool = False,
 ) -> EligibleTerminations:
     """Return one page of candidates for a canonical termination field key.
 
@@ -340,12 +358,15 @@ def eligible_terminations(
     query.
     """
     parsed = parse_termination_field_key(field_key)
-    device_name, kind = parsed["device"], parsed["kind"]
+    kind = parsed["kind"]
     accessor = _READER_ACCESSOR_BY_KIND[kind]
-    devices = _visible_devices(netbox_reader, [device_name]).get(identity_text(device_name), [])
-    if len(devices) != 1:
+    device = (
+        resolved_device_for(field_key, netbox_reader, _lock_rows=_lock_rows)
+        if _resolved_device is _RESOLVED_DEVICE_UNSET
+        else _resolved_device
+    )
+    if device is None:
         return EligibleTerminations(candidates=(), total=0)
-    device = devices[0]
     candidates = getattr(netbox_reader, accessor)().filter(device_id=device.pk)
     if parsed["role"] == MAPPED_PEER_ROLE:
         from .models import TerminationResolution, index_digest
@@ -399,6 +420,8 @@ def eligible_terminations(
         )
     if search:
         candidates = candidates.filter(name__icontains=search)
+    if _lock_rows:
+        tuple(candidates.order_by("pk").select_for_update(of=("self",)).values_list("pk", flat=True))
     candidates = candidates.order_by("name", "pk")
     return EligibleTerminations(candidates=tuple(candidates[:limit]), total=candidates.count())