nat-engine 1__py3-none-any.whl

mannf/product/status.py

@@ -0,0 +1,404 @@
+# 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.
+
+"""Component health-check helpers for the NAT status endpoint.
+
+Each public ``check_*`` coroutine returns a :class:`ComponentResult` that
+describes the health of one subsystem.  :func:`run_all_checks` aggregates
+them into a list and :func:`aggregate_status` derives the overall status.
+
+Statuses
+--------
+- ``healthy``   — the component is reachable and operating normally.
+- ``degraded``  — the component is reachable but reporting a non-critical issue.
+- ``unhealthy`` — the component is critical and unavailable.
+- ``disabled``  — the component is not configured (missing env var).
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+import time
+from typing import Any, Dict, List
+
+from mannf import __version__
+
+# ---------------------------------------------------------------------------
+# Data class
+# ---------------------------------------------------------------------------
+
+
+class ComponentResult:
+    """Structured result returned by each component health-check function."""
+
+    __slots__ = ("name", "status", "latency_ms", "details")
+
+    def __init__(
+        self,
+        name: str,
+        status: str,
+        latency_ms: float,
+        details: Dict[str, Any],
+    ) -> None:
+        self.name = name
+        self.status = status
+        self.latency_ms = latency_ms
+        self.details = details
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "status": self.status,
+            "latency_ms": round(self.latency_ms, 3),
+            "details": self.details,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Individual component checks
+# ---------------------------------------------------------------------------
+
+
+async def check_database() -> ComponentResult:
+    """Probe the PostgreSQL database with a lightweight ``SELECT 1``."""
+    from mannf.product.database import _get_database_url
+
+    if _get_database_url() is None:
+        return ComponentResult(
+            name="database",
+            status="disabled",
+            latency_ms=0.0,
+            details={"reason": "DATABASE_URL not configured"},
+        )
+
+    t0 = time.perf_counter()
+    try:
+        from mannf.product.database import _build_engine
+        from sqlalchemy import text
+
+        engine = _build_engine()
+        if engine is None:
+            return ComponentResult(
+                name="database",
+                status="unhealthy",
+                latency_ms=0.0,
+                details={"error": "Engine could not be initialised"},
+            )
+
+        details: Dict[str, Any] = {"engine": "postgresql"}
+
+        # Collect pool stats when available
+        try:
+            pool = engine.pool
+            details["pool_size"] = pool.size()
+            details["pool_checked_out"] = pool.checkedout()
+        except Exception:  # noqa: BLE001
+            pass
+
+        async with engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+
+        latency_ms = (time.perf_counter() - t0) * 1000
+        return ComponentResult(
+            name="database",
+            status="healthy",
+            latency_ms=latency_ms,
+            details=details,
+        )
+    except Exception as exc:  # noqa: BLE001
+        latency_ms = (time.perf_counter() - t0) * 1000
+        return ComponentResult(
+            name="database",
+            status="unhealthy",
+            latency_ms=latency_ms,
+            details={"error": str(exc)},
+        )
+
+
+async def check_blob_storage() -> ComponentResult:
+    """Check whether Azure Blob Storage is configured and reachable."""
+    conn_string = os.environ.get("NAT_BLOB_STORAGE_CONNECTION_STRING", "").strip()
+    if not conn_string:
+        return ComponentResult(
+            name="blob_storage",
+            status="disabled",
+            latency_ms=0.0,
+            details={"reason": "NAT_BLOB_STORAGE_CONNECTION_STRING not configured"},
+        )
+
+    t0 = time.perf_counter()
+    try:
+        from azure.storage.blob import BlobServiceClient  # type: ignore[import]
+
+        client = BlobServiceClient.from_connection_string(conn_string)
+        # Lightweight probe: list containers (first page only, max_results=1)
+        props = client.get_service_properties()
+        latency_ms = (time.perf_counter() - t0) * 1000
+        return ComponentResult(
+            name="blob_storage",
+            status="healthy",
+            latency_ms=latency_ms,
+            details={"provider": "azure_blob_storage"},
+        )
+    except ImportError:
+        latency_ms = (time.perf_counter() - t0) * 1000
+        return ComponentResult(
+            name="blob_storage",
+            status="degraded",
+            latency_ms=latency_ms,
+            details={
+                "reason": "azure-storage-blob SDK not installed",
+                "connection_string_set": True,
+            },
+        )
+    except Exception as exc:  # noqa: BLE001
+        latency_ms = (time.perf_counter() - t0) * 1000
+        return ComponentResult(
+            name="blob_storage",
+            status="unhealthy",
+            latency_ms=latency_ms,
+            details={"error": str(exc)},
+        )
+
+
+async def check_telemetry() -> ComponentResult:
+    """Report whether Application Insights is configured (informational only)."""
+    conn_string = os.environ.get("APPLICATIONINSIGHTS_CONNECTION_STRING", "").strip()
+    if not conn_string:
+        return ComponentResult(
+            name="telemetry",
+            status="disabled",
+            latency_ms=0.0,
+            details={
+                "reason": "APPLICATIONINSIGHTS_CONNECTION_STRING not configured",
+                "connection_string_set": False,
+            },
+        )
+    return ComponentResult(
+        name="telemetry",
+        status="healthy",
+        latency_ms=0.0,
+        details={
+            "provider": "azure_application_insights",
+            "connection_string_set": True,
+        },
+    )
+
+
+async def check_scan_queue(scans: Dict[str, Any]) -> ComponentResult:
+    """Report scan queue depth, running count, capacity, and max queue depth."""
+    t0 = time.perf_counter()
+    try:
+        # Import ScanStatus here to avoid circular imports at module level
+        from mannf.product.server import ScanStatus
+
+        running = sum(1 for s in scans.values() if s.get("status") == ScanStatus.RUNNING)
+        queued = sum(1 for s in scans.values() if s.get("status") == ScanStatus.PENDING)
+        capacity = int(os.environ.get("NAT_MAX_CONCURRENT_SCANS", "4"))
+        max_queue_depth = int(os.environ.get("NAT_MAX_QUEUE_DEPTH", "20"))
+
+        latency_ms = (time.perf_counter() - t0) * 1000
+        return ComponentResult(
+            name="scan_queue",
+            status="healthy",
+            latency_ms=latency_ms,
+            details={
+                "running": running,
+                "queued": queued,
+                "capacity": capacity,
+                "max_queue_depth": max_queue_depth,
+            },
+        )
+    except Exception as exc:  # noqa: BLE001
+        latency_ms = (time.perf_counter() - t0) * 1000
+        return ComponentResult(
+            name="scan_queue",
+            status="degraded",
+            latency_ms=latency_ms,
+            details={"error": str(exc)},
+        )
+
+
+def check_server_info(server_start_time: float) -> ComponentResult:
+    """Return static server metadata (synchronous — no I/O needed)."""
+    uptime_seconds = time.monotonic() - server_start_time
+    workers = int(os.environ.get("NAT_WORKERS", "1"))
+    host = os.environ.get("NAT_HOST", "0.0.0.0")
+    port = int(os.environ.get("NAT_PORT", "8080"))
+    return ComponentResult(
+        name="server",
+        status="healthy",
+        latency_ms=0.0,
+        details={
+            "version": __version__,
+            "python_version": sys.version,
+            "platform": platform.platform(),
+            "uptime_seconds": round(uptime_seconds, 1),
+            "workers": workers,
+            "host": host,
+            "port": port,
+        },
+    )
+
+
+def check_environment() -> ComponentResult:
+    """Return environment and deployment metadata (synchronous — no I/O needed).
+
+    Exposes ``NAT_ENV``, canary status, the deployed git SHA, and the
+    deployment timestamp so that monitoring tools and the ``/api/v1/status``
+    response can clearly distinguish staging from production instances and
+    identify which revision is running.
+    """
+    nat_env = os.environ.get("NAT_ENV", "production")
+    is_canary = os.environ.get("CANARY_REVISION", "").lower() in ("true", "1", "yes")
+    deploy_sha = os.environ.get("DEPLOY_SHA", "")
+    deploy_timestamp = os.environ.get("DEPLOY_TIMESTAMP", "")
+    canary_weight_raw = os.environ.get("CANARY_TRAFFIC_WEIGHT", "")
+    canary_weight: Any = None
+    if canary_weight_raw:
+        try:
+            canary_weight = int(canary_weight_raw)
+        except ValueError:
+            canary_weight = canary_weight_raw
+
+    details: Dict[str, Any] = {
+        "environment": nat_env,
+        "is_staging": nat_env == "staging",
+        "is_canary": is_canary,
+    }
+    if deploy_sha:
+        details["deploy_sha"] = deploy_sha
+    if deploy_timestamp:
+        details["deploy_timestamp"] = deploy_timestamp
+    if is_canary and canary_weight is not None:
+        details["canary_traffic_weight"] = canary_weight
+
+    return ComponentResult(
+        name="environment",
+        status="healthy",
+        latency_ms=0.0,
+        details=details,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Aggregation helpers
+# ---------------------------------------------------------------------------
+
+_CRITICAL_COMPONENTS = {"database"}
+
+
+def aggregate_status(components: List[ComponentResult]) -> str:
+    """Derive overall status from per-component results.
+
+    Rules
+    -----
+    - ``unhealthy`` if any **critical** component is unhealthy.
+    - ``degraded`` if any component is degraded.
+    - ``healthy`` if all components are healthy or disabled.
+    """
+    statuses = {c.name: c.status for c in components}
+
+    for name in _CRITICAL_COMPONENTS:
+        if statuses.get(name) == "unhealthy":
+            return "unhealthy"
+
+    if any(s == "degraded" for s in statuses.values()):
+        return "degraded"
+
+    if any(s == "unhealthy" for s in statuses.values()):
+        return "degraded"
+
+    return "healthy"
+
+
+def check_billing() -> ComponentResult:
+    """Report whether Stripe billing is configured and ready.
+
+    Returns ``healthy`` when both ``STRIPE_SECRET_KEY`` and
+    ``STRIPE_WEBHOOK_SECRET`` are present.  Returns ``degraded`` when only
+    the secret key is set (webhook not configured).  Returns ``disabled``
+    when neither key is set — billing is optional for self-hosted deployments.
+    """
+    stripe_key = os.environ.get("STRIPE_SECRET_KEY", "").strip()
+    webhook_secret = os.environ.get("STRIPE_WEBHOOK_SECRET", "").strip()
+
+    if not stripe_key:
+        return ComponentResult(
+            name="billing",
+            status="disabled",
+            latency_ms=0.0,
+            details={
+                "reason": "STRIPE_SECRET_KEY not configured",
+                "stripe_key_set": False,
+                "webhook_secret_set": bool(webhook_secret),
+            },
+        )
+
+    if not webhook_secret:
+        return ComponentResult(
+            name="billing",
+            status="degraded",
+            latency_ms=0.0,
+            details={
+                "reason": "STRIPE_WEBHOOK_SECRET not configured — webhook verification disabled",
+                "stripe_key_set": True,
+                "webhook_secret_set": False,
+                "stripe_mode": "test" if stripe_key.startswith("sk_test_") else "live",
+            },
+        )
+
+    return ComponentResult(
+        name="billing",
+        status="healthy",
+        latency_ms=0.0,
+        details={
+            "stripe_key_set": True,
+            "webhook_secret_set": True,
+            "stripe_mode": "test" if stripe_key.startswith("sk_test_") else "live",
+        },
+    )
+
+
+def check_demo_mode() -> ComponentResult:
+    """Report whether NAT demo mode is active.
+
+    Demo mode is controlled by the ``NAT_DEMO_MODE`` environment variable.
+    When active, Stripe calls use test keys, scan results use synthetic data
+    generators, and rate limits are relaxed for demo walkthroughs.
+    """
+    raw = os.environ.get("NAT_DEMO_MODE", "").lower().strip()
+    is_demo = raw in ("true", "1", "yes")
+
+    return ComponentResult(
+        name="demo_mode",
+        status="healthy",
+        latency_ms=0.0,
+        details={
+            "demo_mode_active": is_demo,
+            "nat_demo_mode": raw or "false",
+        },
+    )
+
+
+async def run_all_checks(scans: Dict[str, Any], server_start_time: float) -> List[ComponentResult]:
+    """Run all component checks and return a list of results."""
+    import asyncio
+
+    results = await asyncio.gather(
+        check_database(),
+        check_blob_storage(),
+        check_telemetry(),
+        check_scan_queue(scans),
+        return_exceptions=False,
+    )
+    results = list(results)
+    results.append(check_server_info(server_start_time))
+    results.append(check_environment())
+    results.append(check_billing())
+    results.append(check_demo_mode())
+    return results

mannf/product/storage/__init__.py

@@ -0,0 +1,10 @@
+# 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.
+
+"""Scan artifact blob storage package."""
+
+from mannf.product.storage.artifact_store import ArtifactStore
+
+__all__ = ["ArtifactStore"]