nat-engine 1__py3-none-any.whl

mannf/product/storage/artifact_store.py

@@ -0,0 +1,343 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Azure Blob Storage backend for scan artifacts.
+
+Blobs are organized as::
+
+    scans/{scan_id}/results.json
+    scans/{scan_id}/spec.yaml
+    scans/{scan_id}/<filename>
+
+When Azure Blob Storage is not configured (neither
+``AZURE_STORAGE_CONNECTION_STRING`` nor ``AZURE_STORAGE_ACCOUNT_NAME`` is
+set), all methods become no-ops that return ``None`` so the rest of the
+application is unaffected.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+_SCANS_CONTAINER = "nat-scans"
+
+
+class ArtifactStore:
+    """Store scan artifacts in Azure Blob Storage.
+
+    Blobs are organized as: ``scans/{scan_id}/results.json``,
+    ``scans/{scan_id}/spec.yaml``, etc.
+
+    When Azure Blob Storage is not configured, all methods return ``None``
+    without raising exceptions so that the application operates normally in
+    local / development mode.
+
+    Parameters
+    ----------
+    container_name:
+        Name of the Azure Blob Storage container.  Defaults to
+        ``"nat-scans"``.
+    """
+
+    def __init__(self, container_name: str = _SCANS_CONTAINER) -> None:
+        self._container_name = container_name
+        self._client: Any = None
+        if self.is_configured():
+            self._client = self._build_client()
+
+    # ------------------------------------------------------------------
+    # Public async API
+    # ------------------------------------------------------------------
+
+    async def store_scan_results(self, scan_id: str, results: Dict[str, Any]) -> Optional[str]:
+        """Store scan results blob.
+
+        Parameters
+        ----------
+        scan_id:
+            Unique scan identifier.  Used as part of the blob path.
+        results:
+            Scan results dict to serialise as JSON.
+
+        Returns
+        -------
+        str | None
+            The URL of the uploaded blob, or ``None`` if Azure is not
+            configured.
+        """
+        if not self._client:
+            return None
+
+        blob_path = f"scans/{scan_id}/results.json"
+        data = json.dumps(results, indent=2, default=str).encode("utf-8")
+        return await self._upload(blob_path, data, content_type="application/json")
+
+    async def retrieve_scan_results(self, scan_id: str) -> Optional[Dict[str, Any]]:
+        """Retrieve scan results from blob storage.
+
+        Parameters
+        ----------
+        scan_id:
+            Unique scan identifier.
+
+        Returns
+        -------
+        dict | None
+            Parsed scan results, or ``None`` if Azure is not configured or
+            the blob does not exist.
+        """
+        if not self._client:
+            return None
+
+        blob_path = f"scans/{scan_id}/results.json"
+        raw = await self._download(blob_path)
+        if raw is None:
+            return None
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            logger.warning("ArtifactStore: corrupt results blob for scan %s", scan_id)
+            return None
+
+    async def store_spec(
+        self,
+        scan_id: str,
+        spec_content: bytes,
+        filename: str,
+    ) -> Optional[str]:
+        """Store the uploaded spec file blob.
+
+        Parameters
+        ----------
+        scan_id:
+            Unique scan identifier.
+        spec_content:
+            Raw bytes of the spec file.
+        filename:
+            Original filename (used as the blob name suffix, e.g.
+            ``"openapi.yaml"``).
+
+        Returns
+        -------
+        str | None
+            The URL of the uploaded blob, or ``None`` if Azure is not
+            configured.
+        """
+        if not self._client:
+            return None
+
+        blob_path = f"scans/{scan_id}/{filename}"
+        return await self._upload(blob_path, spec_content)
+
+    async def store_scan_spec(self, scan_id: str, content: bytes, filename: str) -> Optional[str]:
+        """Store the OpenAPI spec file used for a scan.
+
+        Parameters
+        ----------
+        scan_id:
+            Unique scan identifier.
+        content:
+            Raw bytes of the spec file.
+        filename:
+            Original filename (e.g. ``"openapi.yaml"``).
+
+        Returns
+        -------
+        str | None
+            The URL of the uploaded blob, or ``None`` if Azure is not
+            configured.
+        """
+        return await self.store_spec(scan_id, content, filename)
+
+    async def store_scan_weights(self, scan_id: str, data: Dict[str, Any]) -> Optional[str]:
+        """Store belief-state / weight snapshot for a scan.
+
+        The data is serialised as JSON and stored under
+        ``weights/{scan_id}/belief_states.json`` to enable cross-session
+        transfer learning when running in cloud mode.
+
+        Parameters
+        ----------
+        scan_id:
+            Unique scan identifier.
+        data:
+            Belief state or weight data to persist.
+
+        Returns
+        -------
+        str | None
+            The URL of the uploaded blob, or ``None`` if Azure is not
+            configured.
+        """
+        if not self._client:
+            return None
+
+        blob_path = f"weights/{scan_id}/belief_states.json"
+        raw = json.dumps(data, indent=2, default=str).encode("utf-8")
+        return await self._upload(blob_path, raw, content_type="application/json")
+
+    async def list_scan_artifacts(self, scan_id: str) -> list:
+        """List available artifact blob names for a scan.
+
+        Returns a list of blob names stored under ``scans/{scan_id}/`` and
+        ``weights/{scan_id}/``.  Returns an empty list when Azure is not
+        configured or if no artifacts exist.
+
+        Parameters
+        ----------
+        scan_id:
+            Unique scan identifier.
+
+        Returns
+        -------
+        list[str]
+            Blob names relative to the container root.
+        """
+        if not self._client:
+            return []
+
+        from azure.core.exceptions import AzureError
+
+        prefixes = [f"scans/{scan_id}/", f"weights/{scan_id}/"]
+        names: list = []
+        try:
+            await self._ensure_container()
+            container_client = self._client.get_container_client(self._container_name)
+            for prefix in prefixes:
+                async for blob in container_client.list_blobs(name_starts_with=prefix):
+                    names.append(blob.name)
+        except AzureError:
+            logger.exception("ArtifactStore: failed to list artifacts for scan %s", scan_id)
+        return names
+
+    async def download_artifact(self, blob_name: str) -> Optional[bytes]:
+        """Download a specific artifact by its full blob name.
+
+        Parameters
+        ----------
+        blob_name:
+            Full blob name (as returned by :meth:`list_scan_artifacts`).
+
+        Returns
+        -------
+        bytes | None
+            Raw bytes of the artifact, or ``None`` if not found / not
+            configured.
+        """
+        if not self._client:
+            return None
+        return await self._download(blob_name)
+
+    # ------------------------------------------------------------------
+    # Class-level helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def is_configured() -> bool:
+        """Return ``True`` when Azure Blob Storage environment variables are set."""
+        return bool(
+            os.environ.get("AZURE_STORAGE_CONNECTION_STRING")
+            or os.environ.get("AZURE_STORAGE_ACCOUNT_NAME")
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_client(self):  # type: ignore[return]
+        """Construct an ``AsyncBlobServiceClient`` from environment variables."""
+        try:
+            from azure.storage.blob.aio import BlobServiceClient
+        except ImportError as exc:
+            raise ImportError(
+                "azure-storage-blob is required for ArtifactStore. "
+                "Install it with: pip install 'mannf[azure-storage]'"
+            ) from exc
+
+        conn_str = os.environ.get("AZURE_STORAGE_CONNECTION_STRING")
+        if conn_str:
+            return BlobServiceClient.from_connection_string(conn_str)
+
+        account_name = os.environ.get("AZURE_STORAGE_ACCOUNT_NAME")
+        if account_name:
+            account_key = os.environ.get("AZURE_STORAGE_ACCOUNT_KEY", "")
+            if account_key:
+                conn_str = (
+                    f"DefaultEndpointsProtocol=https;"
+                    f"AccountName={account_name};"
+                    f"AccountKey={account_key};"
+                    f"EndpointSuffix=core.windows.net"
+                )
+                return BlobServiceClient.from_connection_string(conn_str)
+            from azure.identity.aio import DefaultAzureCredential
+            credential = DefaultAzureCredential()
+            return BlobServiceClient(
+                account_url=f"https://{account_name}.blob.core.windows.net",
+                credential=credential,
+            )
+
+        raise EnvironmentError(
+            "Neither AZURE_STORAGE_CONNECTION_STRING nor "
+            "AZURE_STORAGE_ACCOUNT_NAME is set."
+        )
+
+    async def _ensure_container(self) -> None:
+        """Create the container if it does not already exist."""
+        from azure.core.exceptions import ResourceExistsError
+
+        container_client = self._client.get_container_client(self._container_name)
+        try:
+            await container_client.create_container()
+            logger.debug("ArtifactStore: created container %r", self._container_name)
+        except ResourceExistsError:
+            pass
+
+    async def _upload(
+        self,
+        blob_path: str,
+        data: bytes,
+        content_type: str = "application/octet-stream",
+    ) -> Optional[str]:
+        """Upload *data* to *blob_path*, returning the blob URL."""
+        from azure.core.exceptions import AzureError
+        from azure.storage.blob import ContentSettings
+
+        try:
+            await self._ensure_container()
+            blob_client = self._client.get_blob_client(
+                container=self._container_name, blob=blob_path
+            )
+            await blob_client.upload_blob(
+                data,
+                overwrite=True,
+                content_settings=ContentSettings(content_type=content_type),
+            )
+            url = blob_client.url
+            logger.info("ArtifactStore: uploaded %s", blob_path)
+            return url
+        except AzureError:
+            logger.exception("ArtifactStore: failed to upload %s", blob_path)
+            return None
+
+    async def _download(self, blob_path: str) -> Optional[bytes]:
+        """Download *blob_path*, returning raw bytes or ``None`` if not found."""
+        from azure.core.exceptions import AzureError, ResourceNotFoundError
+
+        try:
+            blob_client = self._client.get_blob_client(
+                container=self._container_name, blob=blob_path
+            )
+            stream = await blob_client.download_blob()
+            return await stream.readall()
+        except ResourceNotFoundError:
+            return None
+        except AzureError:
+            logger.exception("ArtifactStore: failed to download %s", blob_path)
+            return None

mannf/product/telemetry.py

@@ -0,0 +1,300 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Application telemetry: Azure Monitor OpenTelemetry + structured JSON logging.
+
+Call :func:`setup_telemetry` once at startup (before the FastAPI app is
+created).  The function is always safe to call:
+
+- When ``APPLICATIONINSIGHTS_CONNECTION_STRING`` is **not** set, it configures
+  a standard human-readable log format suitable for local development and
+  returns immediately.
+- When the connection string **is** set, it additionally:
+  1. Configures Python's root logger to emit structured JSON (useful for any
+     cloud log aggregator, not just Azure).
+  2. Calls ``configure_azure_monitor()`` to enable OpenTelemetry
+     auto-instrumentation (traces, metrics, logs) and ship telemetry to
+     Application Insights.
+
+The Azure SDK dependency (``azure-monitor-opentelemetry``) is **optional at
+runtime** — if it is not installed the module falls back gracefully to JSON
+logging only.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import json
+import logging
+import os
+import traceback
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+# ---------------------------------------------------------------------------
+# Per-request log context (tenant / scan)
+# ---------------------------------------------------------------------------
+
+_log_context: contextvars.ContextVar[Dict[str, Any]] = contextvars.ContextVar(
+    "_log_context", default={}
+)
+
+
+def set_log_context(**kwargs: Any) -> None:
+    """Merge *kwargs* into the current log context for this coroutine/thread.
+
+    Typical usage::
+
+        set_log_context(tenant_id="t-123", scan_id="s-456")
+
+    Call :func:`clear_log_context` when the context is no longer needed (e.g.
+    at the end of an HTTP request).
+    """
+    current = dict(_log_context.get())
+    current.update({k: v for k, v in kwargs.items() if v is not None})
+    _log_context.set(current)
+
+
+def clear_log_context() -> None:
+    """Reset the log context for this coroutine/thread to an empty dict."""
+    _log_context.set({})
+
+
+class TenantContextFilter(logging.Filter):
+    """Inject tenant/scan context fields into every :class:`logging.LogRecord`.
+
+    Fields are drawn from the :data:`_log_context` ContextVar, which is
+    populated by :func:`set_log_context`.  If no context has been set the
+    fields are omitted so that log entries from background tasks or startup
+    code are not polluted with empty values.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:  # noqa: A003
+        ctx = _log_context.get()
+        for key, value in ctx.items():
+            if not hasattr(record, key):
+                setattr(record, key, value)
+        return True
+
+
+# ---------------------------------------------------------------------------
+# Custom OpenTelemetry metric instruments
+# ---------------------------------------------------------------------------
+# These are initialised lazily in setup_telemetry() and fall back to no-op
+# stubs when OpenTelemetry is not configured so that callers can always use
+# them without checking for None.
+
+
+class _NoOpCounter:
+    """No-op stand-in for opentelemetry.metrics.Counter."""
+
+    def add(self, amount: float, attributes: Optional[Dict[str, Any]] = None) -> None:
+        pass
+
+
+class _NoOpHistogram:
+    """No-op stand-in for opentelemetry.metrics.Histogram."""
+
+    def record(self, amount: float, attributes: Optional[Dict[str, Any]] = None) -> None:
+        pass
+
+
+class _NoOpGauge:
+    """No-op stand-in for an observable gauge (callback-based metric)."""
+
+    def __init__(self) -> None:
+        self._value: float = 0.0
+
+    def set(self, value: float, attributes: Optional[Dict[str, Any]] = None) -> None:
+        self._value = value
+
+
+# Public metric handles — replaced with real instruments when OTel is available
+scans_started_counter: Any = _NoOpCounter()
+scans_completed_counter: Any = _NoOpCounter()
+scans_duration_histogram: Any = _NoOpHistogram()
+scan_queue_depth_gauge: Any = _NoOpGauge()
+
+
+# ---------------------------------------------------------------------------
+# JSON formatter
+# ---------------------------------------------------------------------------
+
+
+class _JsonFormatter(logging.Formatter):
+    """Emit each log record as a single-line JSON object.
+
+    Fields included in every record:
+    - ``timestamp`` — ISO-8601 UTC
+    - ``level``     — e.g. ``"INFO"``
+    - ``message``   — formatted log message
+    - ``logger``    — logger name
+    - ``module``    — Python module (``record.module``)
+    - ``funcName``  — calling function name
+    - Any *extra* fields attached to the record that are not standard
+      :class:`logging.LogRecord` attributes.
+    """
+
+    # Standard LogRecord attributes we do NOT want to re-emit as extra fields.
+    _RESERVED: frozenset = frozenset({
+        "name", "msg", "args", "created", "filename", "funcName", "levelname",
+        "levelno", "lineno", "message", "module", "msecs", "pathname",
+        "process", "processName", "relativeCreated", "stack_info", "thread",
+        "threadName", "exc_info", "exc_text",
+    })
+
+    def format(self, record: logging.LogRecord) -> str:
+        record.message = record.getMessage()
+
+        payload: Dict[str, Any] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "message": record.message,
+            "logger": record.name,
+            "module": record.module,
+            "funcName": record.funcName,
+        }
+
+        # Attach any extra fields the caller passed via logging.extra
+        for key, value in record.__dict__.items():
+            if key not in self._RESERVED and not key.startswith("_"):
+                payload[key] = value
+
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        elif record.exc_text:
+            payload["exception"] = record.exc_text
+
+        return json.dumps(payload, default=str)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def setup_telemetry() -> None:
+    """Configure logging and (optionally) Azure Monitor OpenTelemetry.
+
+    This function is **idempotent** — calling it multiple times has no
+    additional effect beyond the first call.
+
+    Behaviour
+    ---------
+    - **Always**: configure the root logger's handler.
+    - **When** ``APPLICATIONINSIGHTS_CONNECTION_STRING`` is set:
+      - Switch the root logger to :class:`_JsonFormatter` (structured JSON).
+      - Attempt to call ``configure_azure_monitor()`` from
+        ``azure.monitor.opentelemetry``.  If the package is not installed
+        or the call fails, log a warning and continue — the app will still
+        run with JSON logging.
+      - Attempt to initialise custom OpenTelemetry metric instruments
+        (``nat.scans.started``, ``nat.scans.completed``,
+        ``nat.scans.duration_seconds``, ``nat.scan_queue.depth``).  Falls
+        back to no-op stubs when the OTel SDK is not available.
+    - **Otherwise**: use a standard human-readable format.
+    """
+    global scans_started_counter, scans_completed_counter
+    global scans_duration_histogram, scan_queue_depth_gauge
+
+    connection_string = os.environ.get("APPLICATIONINSIGHTS_CONNECTION_STRING", "").strip()
+
+    root_logger = logging.getLogger()
+
+    # Only add a handler if none exist yet (avoid duplicate output on repeated calls).
+    if not root_logger.handlers:
+        handler = logging.StreamHandler()
+        root_logger.addHandler(handler)
+        root_logger.setLevel(logging.INFO)
+
+    # Register the tenant/scan context filter once (idempotent check).
+    _filter_type = TenantContextFilter
+    if not any(isinstance(f, _filter_type) for f in root_logger.filters):
+        root_logger.addFilter(TenantContextFilter())
+
+    if connection_string:
+        # ── Structured JSON logging ─────────────────────────────────────────
+        for handler in root_logger.handlers:
+            handler.setFormatter(_JsonFormatter())
+
+        # ── Azure Monitor OpenTelemetry ─────────────────────────────────────
+        try:
+            from azure.monitor.opentelemetry import configure_azure_monitor  # type: ignore[import]
+
+            configure_azure_monitor(connection_string=connection_string)
+            logging.getLogger(__name__).info(
+                "Azure Monitor OpenTelemetry configured",
+                extra={"connection_string_present": True},
+            )
+        except ImportError:
+            logging.getLogger(__name__).warning(
+                "azure-monitor-opentelemetry is not installed; "
+                "Application Insights telemetry will not be sent. "
+                "Install it with: pip install azure-monitor-opentelemetry>=1.6"
+            )
+        except Exception:  # noqa: BLE001
+            logging.getLogger(__name__).warning(
+                "Failed to configure Azure Monitor OpenTelemetry:\n%s",
+                traceback.format_exc(),
+            )
+
+        # ── Custom OpenTelemetry metric instruments ─────────────────────────
+        try:
+            from opentelemetry import metrics as _otel_metrics  # type: ignore[import]
+
+            _meter = _otel_metrics.get_meter("mannf.nat", version="1.0")
+            scans_started_counter = _meter.create_counter(
+                name="nat.scans.started",
+                description="Number of scans started",
+                unit="1",
+            )
+            scans_completed_counter = _meter.create_counter(
+                name="nat.scans.completed",
+                description="Number of scans completed (use 'status' attribute for outcome)",
+                unit="1",
+            )
+            scans_duration_histogram = _meter.create_histogram(
+                name="nat.scans.duration_seconds",
+                description="Scan execution duration in seconds",
+                unit="s",
+            )
+
+            # Observable gauge for queue depth — use an up-down counter as a
+            # simple synchronous proxy; the value is updated externally via the
+            # _NoOpGauge.set() interface replaced by a thin wrapper here.
+            class _GaugeProxy(_NoOpGauge):
+                """Wraps an UpDownCounter to simulate a synchronous gauge."""
+
+                def __init__(self, counter: Any) -> None:
+                    super().__init__()
+                    self._counter = counter
+                    self._last_value: float = 0.0
+
+                def set(self, value: float, attributes: Optional[Dict[str, Any]] = None) -> None:
+                    delta = value - self._last_value
+                    self._last_value = value
+                    self._counter.add(delta, attributes or {})
+
+            _queue_depth_counter = _meter.create_up_down_counter(
+                name="nat.scan_queue.depth",
+                description="Current scan queue depth (pending + running)",
+                unit="1",
+            )
+            scan_queue_depth_gauge = _GaugeProxy(_queue_depth_counter)
+
+        except ImportError:
+            # OTel SDK not installed — no-op stubs remain
+            pass
+        except Exception:  # noqa: BLE001
+            logging.getLogger(__name__).warning(
+                "Failed to initialise OpenTelemetry metric instruments:\n%s",
+                traceback.format_exc(),
+            )
+    else:
+        # ── Human-readable format for local development ────────────────────
+        fmt = "%(asctime)s %(levelname)-8s %(name)s — %(message)s"
+        for handler in root_logger.handlers:
+            handler.setFormatter(logging.Formatter(fmt))