netbox-data-import 2.3.0__tar.gz → 2.4.0__tar.gz

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/PKG-INFO

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

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/__init__.py

@@ -4,7 +4,7 @@ from typing import Any
 
 from netbox.plugins import PluginConfig
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"
 
 
 class NetBoxDataImportConfig(PluginConfig):

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/adapters.py

@@ -13,13 +13,14 @@ the NetBox boundary.
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING
 
 from .catalog import OutputKind, has_implemented_module
+from .values import identity_text
 
 if TYPE_CHECKING:
-    from .trace_workbook import SourceTrace
+    from .source_trace import SourceTrace
 
 
 class UnknownSourceAdapter(Exception):
@@ -39,6 +40,16 @@ class SourceDiagnostic:
     row_number: int | None = None
 
 
+def _foreign_row_number(row) -> int | None:
+    """Return the source row a foreign row states, so its diagnostic can name a location."""
+    provenance = getattr(row, "provenance", ())
+    if provenance:
+        return provenance[0].row_start
+    if isinstance(row, dict):
+        return row.get("_row_number")
+    return None
+
+
 @dataclass(frozen=True)
 class SourceBatch:
     """The typed source items and source diagnostics from one file (section 1)."""
@@ -48,6 +59,46 @@ class SourceBatch:
     diagnostics: tuple[SourceDiagnostic, ...] = ()
     unused_columns: dict[str, dict] = field(default_factory=dict)
 
+    def __post_init__(self):
+        """Exclude a row the output kinds cannot carry, and mark a Trace with empty Device references."""
+        from .source_trace import SourceTrace
+
+        trace_batch = OutputKind.SOURCE_TRACE in self.output_kinds
+        expected = SourceTrace if trace_batch else dict
+        carries = "Source Traces" if trace_batch else "source rows"
+        rows = []
+        diagnostics = list(self.diagnostics)
+        for row in self.rows:
+            if not isinstance(row, expected):
+                # Excluded here, because every reader below reads the row the output kinds declare.
+                diagnostics.append(
+                    SourceDiagnostic(
+                        code="source.row_type_unexpected",
+                        message=f"This batch carries {carries} only; got {type(row).__name__}.",
+                        row_number=_foreign_row_number(row),
+                    )
+                )
+                continue
+            if not trace_batch:
+                rows.append(row)
+                continue
+            summary = row.endpoint_summary
+            references = [summary.from_termination, summary.to_termination, *row.corroboration]
+            for segment in row.segments:
+                references.extend((segment.left, segment.right))
+            if all(identity_text(reference.device) for reference in references):
+                rows.append(row)
+                continue
+            diagnostic = SourceDiagnostic(
+                code="trace.device_required",
+                message="A Source Trace Termination Reference must name a Device.",
+                row_number=row.provenance[0].row_start,
+            )
+            diagnostics.append(diagnostic)
+            rows.append(replace(row, errors=(*row.errors, diagnostic)))
+        object.__setattr__(self, "rows", tuple(rows))
+        object.__setattr__(self, "diagnostics", tuple(diagnostics))
+
 
 class SourceAdapter:
     """Base class for a Source Adapter declaration."""

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/cable_target.py

@@ -36,6 +36,13 @@ from .field_keys import (
 from .object_permissions import enforce_saved_object_permission
 from .plan import Diagnostic, Disposition, PlannedChange, Severity, SynchronizationUnit
 from .target_runtime import DeletedObject, PreconditionFailed
+from .trace_device_resolution import (
+    STALE as DEVICE_STALE,
+    collect_trace_device_evidence,
+    resolve_trace_devices,
+    resolved_trace_device,
+    source_device_key,
+)
 from .values import identity_text, source_text
 
 CABLE_STATUS = "connected"
@@ -207,7 +214,9 @@ class _TraceAnalysis:
     segments: list = field(default_factory=list)
     proven: dict = field(default_factory=dict)
     policies: dict = field(default_factory=dict)
+    devices: dict = field(default_factory=dict)
     terminations: dict = field(default_factory=dict)
+    resolution_started: bool = False
     topology_read: bool = False
     logical_cable: Any = None
     retains_logical_cable: bool = False
@@ -303,38 +312,19 @@ def _source_record(trace, segment_index: int) -> dict:
     }
 
 
-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
-
-    wanted = {identity_text(name) for name in names if identity_text(name)}
-    if not wanted:
-        return {}
-    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)
-    grouped: dict[str, list] = {}
-    for device in devices.filter(lookup):
-        comparison = identity_text(device.name)
-        if comparison in wanted:
-            grouped.setdefault(comparison, []).append(device)
-    return grouped
-
-
-def resolved_device_for(field_key: str, netbox_reader, *, _lock_rows=False):
+def resolved_device_for(field_key: str, netbox_reader, *, profile, _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
+    return resolved_trace_device(
+        profile=profile,
+        reader=netbox_reader,
+        source_label=device_name,
+        lock_rows=_lock_rows,
+    )
 
 
 _RESOLVED_DEVICE_UNSET = object()
@@ -361,7 +351,7 @@ def eligible_terminations(
     kind = parsed["kind"]
     accessor = _READER_ACCESSOR_BY_KIND[kind]
     device = (
-        resolved_device_for(field_key, netbox_reader, _lock_rows=_lock_rows)
+        resolved_device_for(field_key, netbox_reader, profile=profile, _lock_rows=_lock_rows)
         if _resolved_device is _RESOLVED_DEVICE_UNSET
         else _resolved_device
     )
@@ -430,6 +420,7 @@ class _CableBatch:
     """Plan every Source Trace in one batch, so an identical shared segment plans once."""
 
     def __init__(self, traces, profile, netbox_reader, *, lock_plan_references: bool = False):
+        traces = tuple(traces)
         self.profile = profile
         self.reader = netbox_reader
         self.actor = netbox_reader.actor
@@ -445,7 +436,14 @@ class _CableBatch:
         self._occupied: dict[tuple[str, int], _ExistingCable] = {}
         self._mapping_rows: dict[str, Any] | None = None
         self._stored = self._stored_resolutions()
-        self._devices = self._load_devices()
+        active_traces = (analysis.trace for analysis in self.analyses if not analysis.stopped)
+        self._device_evidence = collect_trace_device_evidence(active_traces)
+        self._device_resolutions = resolve_trace_devices(
+            profile=self.profile,
+            reader=self.reader,
+            evidence=self._device_evidence,
+            lock_rows=self.lock_plan_references,
+        )
         self._resolve_terminations()
         self._load_mappings()
         self._build_segments()
@@ -512,16 +510,6 @@ class _CableBatch:
         ).select_related("selected_object_type")
         return {row.field_key: row for row in rows}
 
-    def _load_devices(self) -> dict[str, list]:
-        """Return the visible Devices every planned trace names, grouped by comparison name."""
-        names = [
-            reference.device
-            for analysis in self.analyses
-            if not analysis.stopped
-            for reference in self._references(analysis.trace)
-        ]
-        return _visible_devices(self.reader, names)
-
     def _components_for(self, device_id: int, kind: str) -> dict[str, list]:
         """Return one Device's terminations of one kind, grouped by comparison name."""
         cached = self._components.get((device_id, kind))
@@ -537,6 +525,7 @@ class _CableBatch:
         for analysis in self.analyses:
             if analysis.stopped:
                 continue
+            analysis.resolution_started = True
             resolved: dict[tuple, _Termination] = {}
             for reference in self._references(analysis.trace):
                 if reference.identity_key in resolved:
@@ -548,19 +537,24 @@ class _CableBatch:
 
     def _resolve_one(self, analysis: _TraceAnalysis, reference) -> _Termination | None:
         """Return the NetBox object one Termination Reference names, or record the open decision."""
-        devices = self._devices.get(identity_text(reference.device), [])
-        if len(devices) != 1:
-            analysis.block("trace.device_unresolved", {**_reference_display(reference), "matches": len(devices)})
+        resolution = self._device_resolutions[source_device_key(reference.device)]
+        analysis.devices.setdefault(resolution.evidence.key, resolution.to_question())
+        if resolution.device is None:
+            code = "trace.device_resolution_stale" if resolution.state == DEVICE_STALE else "trace.device_unresolved"
+            analysis.block(
+                code,
+                {**_reference_display(reference), "matches": resolution.exact_match_count},
+            )
             # With no resolved Device there is nothing to pick from, so the picker cannot help here.
             self._record_resolution(
                 analysis,
                 reference,
                 UNRESOLVED,
                 None,
-                reason=f"The source names {len(devices)} matching Devices, so no port list applies.",
+                reason="Resolve the source Device before choosing one of its ports.",
             )
             return None
-        device = devices[0]
+        device = resolution.device
         stored = self._stored.get(_field_key(reference))
         if stored is not None:
             termination = self._stored_termination(analysis, reference, device, stored)
@@ -1222,9 +1216,11 @@ class _CableBatch:
             },
             "segments": segments,
             "logical_cable": self._logical_cable_display(analysis),
+            "resolution_started": analysis.resolution_started,
             "topology_known": analysis.topology_read,
             # A unit with no changes proposes nothing, so the panel must not offer to delete one.
             "deletes_logical_cable": writes and analysis.deleted_logical_cable is not None,
+            "devices": list(analysis.devices.values()),
             "terminations": list(analysis.terminations.values()),
         }
 

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/catalog.py

@@ -259,6 +259,7 @@ POLICY_SECTIONS: tuple[PolicySection, ...] = (
     PolicySection("source_resolutions", "Source Resolutions", _DEVICE_ONLY),
     PolicySection("device_existing_matches", "Device Existing Matches", _DEVICE_ONLY),
     PolicySection("ignored_field_differences", "Ignored Field Differences", _DEVICE_ONLY),
+    PolicySection("trace_device_resolutions", "Trace Device Resolutions", _TRACE_ONLY),
     PolicySection("termination_resolutions", "Termination Resolutions", _TRACE_ONLY),
     PolicySection("cable_class_mappings", "CableClass Mappings", _TRACE_ONLY),
 )

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/forms.py

@@ -3,6 +3,7 @@
 import copy
 
 from django import forms
+from django.utils.html import format_html
 from dcim.models import Site, Location
 from tenancy.models import Tenant
 from netbox.forms import NetBoxModelBulkEditForm, NetBoxModelForm, NetBoxModelImportForm
@@ -25,6 +26,24 @@ from .models import (
 
 _EXPLICIT_NONE = "__explicit_none__"
 
+_CREDENTIAL_REFERENCE_EXAMPLE = """{
+  "backend": "vault_kv_v2",
+  "mount": "secret",
+  "path": "inference/backend",
+  "field": "api_key"
+}"""
+
+_CREDENTIAL_REFERENCE_HELP = format_html(
+    "This JSON tells the plugin where to find the API key in Vault. It does not contain the API key. "
+    "Configure Vault first in the NetBox plugin settings at "
+    "<code>PLUGINS_CONFIG[&quot;netbox_data_import&quot;][&quot;vault&quot;]</code>. "
+    '<details class="mt-1" data-credential-reference-help>'
+    "<summary>Show the required JSON shape</summary>"
+    '<pre class="mt-2 mb-0"><code>{}</code></pre>'
+    "</details>",
+    _CREDENTIAL_REFERENCE_EXAMPLE,
+)
+
 
 class _RuntimeCableChoiceField(forms.ChoiceField):
     """Render only current choices while letting shared validation classify submitted values."""
@@ -132,7 +151,7 @@ class ImportProfileForm(NetBoxModelForm):
             return self.instance.source_adapter
         if self.is_bound:
             return self.data.get(self.add_prefix("source_adapter")) or self.instance.source_adapter
-        return self.instance.source_adapter
+        return self.initial.get("source_adapter") or self.instance.source_adapter
 
     def clean(self):
         """Collect the adapter-declared fields into ``adapter_config``."""
@@ -306,8 +325,10 @@ class InferenceBackendForm(NetBoxModelForm):
             "tags",
         )
         help_texts = {
-            "credential_reference": (
-                "A typed Vault KV v2 reference: backend, mount, path and field. It never holds a key value."
+            "credential_reference": _CREDENTIAL_REFERENCE_HELP,
+            "model": (
+                "Enter the exact model id. After you save the backend, run the connection test to discover "
+                "model suggestions when the endpoint supports them."
             ),
         }
 

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/import_engine.py

@@ -18,7 +18,7 @@ from django.db import DatabaseError
 from . import adapter_config, adapters, catalog, target_modules
 from .models import FailureReason, ImportExecution, SourceDocument, locked_profile_policy
 from .netbox_reader import NetBoxReader, PlanningTargetUnavailable
-from .object_permissions import ObjectPermissionDenied
+from .object_permissions import ObjectPermissionDenied, clear_user_permission_caches
 from .plan import Diagnostic, Disposition, ImportPlan, PlanInvalid, Severity, executable_units, merge_changes
 from .source_resolution import derive_effective_rows
 from .target_runtime import DeletedObject, ExecutionContext, PreconditionFailed
@@ -225,6 +225,7 @@ class ImportEngine:
         progress_callback,
     ) -> None:
         """Compare the selection against a fresh plan and apply it, inside the caller's transaction."""
+        clear_user_permission_caches(actor)
         current = cls.plan(
             profile,
             source_document,
@@ -253,6 +254,7 @@ class ImportEngine:
             if runtime is None:
                 raise EngineConfigurationError(f"No Target Module runtime is registered for '{change.target_module}'.")
             try:
+                clear_user_permission_caches(actor)
                 applied = runtime.apply(change, context)
             except (PreconditionFailed, ObjectPermissionDenied, ValidationError, DatabaseError) as exc:
                 raise _ExecutionFailed(

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/inference_adapter.py

@@ -2,9 +2,9 @@
 # SPDX-FileCopyrightText: 2026 Marcin Zieba <marcinpsk@gmail.com>
 """The OpenAI-compatible Inference Backend adapter (specification 8.1, 8.3, 8.4).
 
-One non-streaming Chat Completions call, built entirely from configuration. The adapter knows
-nothing about NetBox, candidates, proposals or jobs: it takes an InferenceRequest and returns an
-InferenceCompletion, or raises a typed backend error.
+The adapter makes one non-streaming Chat Completions call and can discover optional model-id
+suggestions. It knows nothing about NetBox, candidates, proposals or jobs: it takes an
+InferenceRequest and returns an InferenceCompletion, or raises a typed backend error.
 
 A returned completion means the call reached the backend and the envelope parsed. Deciding what the
 content means belongs to the application service, not here.
@@ -19,7 +19,15 @@ from contextlib import suppress
 import requests
 from urllib3.exceptions import ReadTimeoutError
 
-from .inference_transport import ResponseProcessingFailure, is_preconnect_failure, request_to_resolved_address
+from .inference_transport import (
+    ResponseBodyTooLarge,
+    ResponseProcessingFailure,
+    WallClockDeadline,
+    WallClockDeadlineExceeded,
+    is_preconnect_failure,
+    request_to_resolved_address,
+)
+from .inference_settings import MODEL_MAX_LENGTH
 from .inference_trust import (
     InvalidInferenceConfiguration,
     assert_resolved_address_allowed,
@@ -28,6 +36,10 @@ from .inference_trust import (
 )
 
 CHAT_COMPLETIONS_PATH = "/chat/completions"
+MODELS_PATH = "/models"
+CHAT_COMPLETION_RESPONSE_LIMIT = 65_536
+MODEL_DISCOVERY_LIMIT = 100
+MODEL_DISCOVERY_RESPONSE_LIMIT = 65_536
 DIAGNOSTIC_TEXT_LIMIT = 4096
 
 # Section 8.4 rejects every other terminal reason: only a completed answer is a completion.
@@ -193,6 +205,46 @@ def _retry_after(response) -> int | None:
         return None
 
 
+def _status_failure(status: int, diagnostic, retry_after: int | None) -> InferenceBackendError | None:
+    """Return the typed failure one HTTP status maps to, or None when the status carries none."""
+    if 300 <= status < 400:
+        return InvalidBackendConfiguration(
+            f"The backend redirected the call (HTTP {status}), which is not followed.", diagnostic=diagnostic
+        )
+    if status in (401, 403):
+        return AuthenticationFailure(f"The backend refused the credential (HTTP {status}).", diagnostic=diagnostic)
+    if status == 429:
+        return RateLimited("The backend rate limited the call.", retry_after=retry_after, diagnostic=diagnostic)
+    if status in TRANSIENT_STATUSES:
+        return TransportFailure(f"The backend answered HTTP {status}.", diagnostic=diagnostic)
+    if status >= 400:
+        return InvalidBackendConfiguration(
+            f"The backend rejected the request (HTTP {status}), which repeating cannot fix.",
+            diagnostic=diagnostic,
+        )
+    return None
+
+
+def _processing_failure(exc: ResponseProcessingFailure, api_key: str) -> InferenceBackendError:
+    """Return the typed failure one interrupted or refused response body maps to."""
+    diagnostic = ResponseDiagnostic(receipt=BODY_INTERRUPTED, status_code=exc.response.status_code)
+    if isinstance(exc.cause, ResponseBodyTooLarge):
+        # The body is refused unread, so the status is the only classification left.
+        return _status_failure(exc.response.status_code, diagnostic, _retry_after(exc.response)) or MalformedEnvelope(
+            "The backend response is too large.", diagnostic=diagnostic
+        )
+    if isinstance(exc.cause, ValueError):
+        return InvalidBackendConfiguration(
+            f"The backend answered with a location this delivery cannot use ({type(exc.cause).__name__}).",
+            diagnostic=_diagnostic(exc.response, api_key),
+        )
+    if isinstance(exc.cause, requests.Timeout) or _is_response_read_timeout(exc.cause):
+        return BackendTimeout(
+            "The backend did not finish its answer inside the configured limits.", diagnostic=diagnostic
+        )
+    return TransportFailure(f"The backend answer was interrupted ({type(exc.cause).__name__}).", diagnostic=diagnostic)
+
+
 def _is_response_read_timeout(exc: Exception) -> bool:
     """Return whether Requests timed out after it had received response headers."""
     return isinstance(exc, requests.ConnectionError) and bool(exc.args) and isinstance(exc.args[0], ReadTimeoutError)
@@ -211,6 +263,7 @@ class OpenAICompatibleAdapter:
         connect_timeout: int = 5,
         read_timeout: int = 60,
         session: "requests.Session | None" = None,
+        deadline: WallClockDeadline | None = None,
     ):
         # Verbatim: normalizing here would pass the request-time recheck a value the form refuses.
         self.api_root = api_root
@@ -221,6 +274,7 @@ class OpenAICompatibleAdapter:
         self.connect_timeout = connect_timeout
         self.read_timeout = read_timeout
         self._session = session or requests.Session()
+        self._deadline = deadline
 
     def _check_response_mode(self, request: InferenceRequest) -> None:
         """Reject a request for a mode this backend is not configured to serve."""
@@ -253,17 +307,32 @@ class OpenAICompatibleAdapter:
         """Return all approved addresses, rechecking the destination at request time."""
         try:
             validate_api_root(self.api_root, self.allowlist, self.authentication)
-            addresses = resolve_addresses(self.api_root)
+            addresses = (
+                resolve_addresses(self.api_root)
+                if self._deadline is None
+                else self._deadline.run(resolve_addresses, self.api_root)
+            )
             assert_resolved_address_allowed(self.api_root, self.allowlist, addresses)
+        except WallClockDeadlineExceeded:
+            raise BackendTimeout("The connection test exceeded its overall time limit.") from None
         except InvalidInferenceConfiguration as exc:
             raise InvalidBackendConfiguration(str(exc)) from None
         return addresses
 
-    def complete(self, request: InferenceRequest, api_key: str) -> InferenceCompletion:
-        """Return one completion, or raise the typed error the backend condition maps to."""
-        self._check_response_mode(request)
+    def _send(
+        self,
+        method: str,
+        path: str,
+        api_key: str,
+        *,
+        response_body_limit: int,
+        **kwargs,
+    ) -> requests.Response:
+        """Send one authenticated request through the checked and pinned destination boundary."""
         resolved_addresses = self._resolved_destinations()
-        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        headers = {"Accept": "application/json"}
+        if "json" in kwargs:
+            headers["Content-Type"] = "application/json"
         if self.authentication == "bearer":
             headers["Authorization"] = f"Bearer {api_key}"
         connection_failure: requests.RequestException | None = None
@@ -271,31 +340,19 @@ class OpenAICompatibleAdapter:
             try:
                 response = request_to_resolved_address(
                     self._session,
-                    "POST",
-                    f"{self.api_root}{CHAT_COMPLETIONS_PATH}",
+                    method,
+                    f"{self.api_root}{path}",
                     resolved_address,
-                    json=self._body(request),
                     headers=headers,
                     timeout=(self.connect_timeout, self.read_timeout),
+                    deadline=self._deadline,
+                    response_body_limit=response_body_limit,
                     # A redirect is a different destination, so it is refused rather than followed.
                     allow_redirects=False,
+                    **kwargs,
                 )
             except ResponseProcessingFailure as exc:
-                if isinstance(exc.cause, ValueError):
-                    raise InvalidBackendConfiguration(
-                        f"The backend answered with a location this delivery cannot use ({type(exc.cause).__name__}).",
-                        diagnostic=_diagnostic(exc.response, api_key),
-                    ) from None
-                diagnostic = ResponseDiagnostic(receipt=BODY_INTERRUPTED, status_code=exc.response.status_code)
-                if isinstance(exc.cause, requests.Timeout) or _is_response_read_timeout(exc.cause):
-                    raise BackendTimeout(
-                        "The backend did not finish its answer inside the configured limits.",
-                        diagnostic=diagnostic,
-                    ) from None
-                raise TransportFailure(
-                    f"The backend answer was interrupted ({type(exc.cause).__name__}).",
-                    diagnostic=diagnostic,
-                ) from None
+                raise _processing_failure(exc, api_key) from None
             except requests.ConnectTimeout as exc:
                 connection_failure = exc
                 continue
@@ -321,7 +378,7 @@ class OpenAICompatibleAdapter:
                 raise InvalidBackendConfiguration(
                     f"The backend answered with a location this delivery cannot use ({type(exc).__name__})."
                 ) from None
-            return self._read(response, api_key)
+            return response
 
         if isinstance(connection_failure, requests.ConnectTimeout):
             raise BackendTimeout("The backend did not answer inside the configured limits.") from None
@@ -330,28 +387,68 @@ class OpenAICompatibleAdapter:
             diagnostic=ABSENT_DIAGNOSTIC,
         ) from None
 
+    @staticmethod
+    def _raise_for_status(response: requests.Response, api_key: str) -> ResponseDiagnostic:
+        """Return a safe diagnostic for success, or raise the typed HTTP failure."""
+        diagnostic = _diagnostic(response, api_key)
+        failure = _status_failure(response.status_code, diagnostic, _retry_after(response))
+        if failure is not None:
+            raise failure
+        return diagnostic
+
+    def complete(self, request: InferenceRequest, api_key: str) -> InferenceCompletion:
+        """Return one completion, or raise the typed error the backend condition maps to."""
+        self._check_response_mode(request)
+        response = self._send(
+            "POST",
+            CHAT_COMPLETIONS_PATH,
+            api_key,
+            response_body_limit=CHAT_COMPLETION_RESPONSE_LIMIT,
+            json=self._body(request),
+        )
+        return self._read(response, api_key)
+
+    def discover_models(self, api_key: str) -> tuple[str, ...]:
+        """Return bounded model-id suggestions from a compatible optional models endpoint."""
+        response = self._send(
+            "GET",
+            MODELS_PATH,
+            api_key,
+            response_body_limit=MODEL_DISCOVERY_RESPONSE_LIMIT,
+        )
+        diagnostic = self._raise_for_status(response, api_key)
+        if diagnostic.redacted:
+            raise MalformedEnvelope("The backend model list contained credential material.", diagnostic=diagnostic)
+        try:
+            envelope = response.json()
+        except (ValueError, RecursionError):
+            raise MalformedEnvelope("The backend model list is not JSON.", diagnostic=diagnostic) from None
+        if not isinstance(envelope, dict) or not isinstance(envelope.get("data"), list):
+            raise MalformedEnvelope("The backend did not provide a compatible model list.", diagnostic=diagnostic)
+
+        models = []
+        seen = set()
+        for item in envelope["data"]:
+            model_id = item.get("id") if isinstance(item, dict) else None
+            if (
+                not isinstance(model_id, str)
+                or not model_id
+                or model_id != model_id.strip()
+                or not model_id.isprintable()
+                or len(model_id) > MODEL_MAX_LENGTH
+                or model_id in seen
+            ):
+                continue
+            seen.add(model_id)
+            models.append(model_id)
+            if len(models) == MODEL_DISCOVERY_LIMIT:
+                break
+        return tuple(models)
+
     def _read(self, response, api_key: str = "") -> InferenceCompletion:
         """Classify the answer, then parse the one envelope a completed call returns."""
-        # Captured before any classification, so every failure below can carry what it received.
-        diagnostic = _diagnostic(response, api_key)
-        status = response.status_code
-        if status in (301, 302, 303, 307, 308):
-            raise InvalidBackendConfiguration(
-                f"The backend redirected the call (HTTP {status}), which is not followed.", diagnostic=diagnostic
-            )
-        if status in (401, 403):
-            raise AuthenticationFailure(f"The backend refused the credential (HTTP {status}).", diagnostic=diagnostic)
-        if status == 429:
-            raise RateLimited(
-                "The backend rate limited the call.", retry_after=_retry_after(response), diagnostic=diagnostic
-            )
-        if status in TRANSIENT_STATUSES:
-            raise TransportFailure(f"The backend answered HTTP {status}.", diagnostic=diagnostic)
-        if status >= 400:
-            raise InvalidBackendConfiguration(
-                f"The backend rejected the request (HTTP {status}), which repeating cannot fix.",
-                diagnostic=diagnostic,
-            )
+        # Captured before any parsing, so every failure below can carry what it received.
+        diagnostic = self._raise_for_status(response, api_key)
         try:
             envelope = response.json()
         except (ValueError, RecursionError):
@@ -405,6 +502,8 @@ def encode_payload(value) -> str:
 
 __all__ = (
     "CHAT_COMPLETIONS_PATH",
+    "MODELS_PATH",
+    "MODEL_DISCOVERY_LIMIT",
     "AuthenticationFailure",
     "BackendTimeout",
     "InferenceBackendError",

{netbox_data_import-2.3.0 → netbox_data_import-2.4.0}/netbox_data_import/inference_backend.py

@@ -93,6 +93,24 @@ class ResolvedInferenceBackend:
         }
 
 
+def adapter_for_backend(backend: ResolvedInferenceBackend, *, deadline=None):
+    """Build the adapter that both proposal jobs and foreground tests use for this backend."""
+    if backend.adapter_type != "openai_compatible":
+        raise InvalidInferenceConfiguration(f"Unsupported Inference Backend adapter '{backend.adapter_type}'.")
+    from .inference_adapter import OpenAICompatibleAdapter
+
+    return OpenAICompatibleAdapter(
+        api_root=backend.api_root,
+        model=backend.model,
+        allowlist=origin_allowlist(),
+        authentication=backend.authentication,
+        response_mode=backend.response_mode,
+        connect_timeout=backend.connect_timeout,
+        read_timeout=backend.read_timeout,
+        deadline=deadline,
+    )
+
+
 def _from_row(row, allowlist) -> ResolvedInferenceBackend:
     """Return the resolved backend one enabled database row describes."""
     # A saved row outlives the allowlist that approved it, so spec 8.3 validates both sources alike.