nat-engine 1__py3-none-any.whl

mannf/product/dashboard/static/manifest.json

@@ -0,0 +1,25 @@
+{
+  "name": "NAT Dashboard — NeuroAgentTest",
+  "short_name": "NAT",
+  "description": "AI-powered API testing dashboard with live agent activity, risk heatmaps, and security findings.",
+  "start_url": "/dashboard",
+  "scope": "/",
+  "display": "standalone",
+  "orientation": "any",
+  "theme_color": "#1f6feb",
+  "background_color": "#0d1117",
+  "icons": [
+    {
+      "src": "/pwa-icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any maskable"
+    },
+    {
+      "src": "/pwa-icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any maskable"
+    }
+  ]
+}

mannf/product/dashboard/static/sw.js

@@ -0,0 +1,64 @@
+// NAT Dashboard — Service Worker
+// Caches static assets for offline/PWA use.
+
+const CACHE_NAME = 'nat-dashboard-v1';
+
+// Assets to pre-cache on install
+const PRECACHE_URLS = [
+  '/dashboard',
+  'https://cdn.jsdelivr.net/npm/chart.js@4.4.2/dist/chart.umd.min.js',
+];
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
+  );
+  // Activate immediately without waiting for existing clients to close
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  // Remove any old caches from previous versions
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(
+        keys
+          .filter((key) => key !== CACHE_NAME)
+          .map((key) => caches.delete(key))
+      )
+    )
+  );
+  self.clients.claim();
+});
+
+self.addEventListener('fetch', (event) => {
+  const { request } = event;
+  const url = new URL(request.url);
+
+  // Only handle GET requests; skip cross-origin requests except Chart.js CDN
+  if (request.method !== 'GET') return;
+
+  // Network-first strategy for API / WebSocket endpoints so live data stays fresh
+  if (url.pathname.startsWith('/api/') || url.pathname.startsWith('/ws/')) {
+    return; // fall through to the network
+  }
+
+  // Cache-first for everything else (dashboard HTML + Chart.js CDN)
+  event.respondWith(
+    caches.match(request).then((cached) => {
+      if (cached) return cached;
+      return fetch(request).then((response) => {
+        // Only cache successful same-origin or CDN responses
+        if (
+          response.ok &&
+          (url.origin === self.location.origin ||
+            url.hostname === 'cdn.jsdelivr.net')
+        ) {
+          const clone = response.clone();
+          caches.open(CACHE_NAME).then((cache) => cache.put(request, clone));
+        }
+        return response;
+      });
+    })
+  );
+});

mannf/product/dashboard/telemetry.py

@@ -0,0 +1,547 @@
+# 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.
+
+"""Telemetry helpers for broadcasting BDI agent state via the dashboard WebSocket.
+
+All public functions are **non-blocking** and **fail-safe** — errors in
+telemetry are silently swallowed so they can never crash a running scan.
+
+Supported event types:
+
+- ``agent_state``      – full agent snapshot after each deliberation cycle
+- ``ecnp_event``       – ECNP contract offer / bid / award lifecycle event
+- ``belief_update``    – incremental belief revision for a single service
+- ``team_annotation``  – user comment added to a finding
+- ``plan_generated``   – LLM test plan generation completed
+- ``schedule_fired``   – a scheduled scan has been triggered
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mannf.core.agents.bdi_agent import BDIAgent
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# In-memory registry: most-recent snapshot per agent (agent_id → payload)
+# ---------------------------------------------------------------------------
+
+_agent_registry: Dict[str, Dict[str, Any]] = {}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+async def _broadcast(payload: Dict[str, Any]) -> None:
+    """Broadcast *payload* via the dashboard WebSocket manager."""
+    from mannf.product.dashboard.app import manager  # lazy to avoid circular import
+
+    await manager.broadcast(payload)
+
+
+# ---------------------------------------------------------------------------
+# Public telemetry functions
+# ---------------------------------------------------------------------------
+
+
+async def broadcast_agent_state(agent: "BDIAgent") -> None:
+    """Broadcast an ``agent_state`` message for *agent* to all WS clients.
+
+    Also updates the in-memory agent registry used by the
+    ``GET /api/v1/dashboard/agents`` REST endpoint.
+    """
+    try:
+        role = type(agent).__name__.replace("Agent", "")
+        intentions = [
+            {
+                "action": i.get("action"),
+                "target": i.get("target"),
+                "score": round(float(i.get("score", 0.0)), 4),
+            }
+            for i in (agent.intentions or [])[:10]
+        ]
+        confidence_per_service = {
+            k: round(float(v), 4) for k, v in agent.beliefs.confidence.items()
+        }
+        beliefs = {
+            k: round(float(v), 4) for k, v in agent.beliefs.fault_likelihood.items()
+        }
+
+        payload: Dict[str, Any] = {
+            "type": "agent_state",
+            "agent_id": agent.agent_id,
+            "agent_role": role,
+            "beliefs": beliefs,
+            "confidence": confidence_per_service,
+            "intentions": intentions,
+            "desires": dict(agent.desires),
+            "entropy": round(agent.beliefs.entropy(), 4),
+            "timestamp": _now_iso(),
+        }
+
+        _agent_registry[agent.agent_id] = payload
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast agent_state", exc_info=True)
+
+
+async def broadcast_ecnp_event(
+    event_kind: str,
+    sender_id: str,
+    contract_id: str,
+    details: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Broadcast an ``ecnp_event`` message to all WebSocket clients.
+
+    Parameters
+    ----------
+    event_kind:
+        One of ``"offer"``, ``"bid"``, or ``"award"``.
+    sender_id:
+        Agent that produced the ECNP message.
+    contract_id:
+        The ``task_id`` that identifies the contract.
+    details:
+        Arbitrary payload (bid cost, awarded agent, test cases, etc.).
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "ecnp_event",
+            "event_kind": event_kind,
+            "sender_id": sender_id,
+            "contract_id": contract_id,
+            "details": details or {},
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast ecnp_event", exc_info=True)
+
+
+async def broadcast_belief_update(
+    agent_id: str,
+    endpoint: str,
+    old_value: float,
+    new_value: float,
+    evidence: float,
+) -> None:
+    """Broadcast a ``belief_update`` message to all WebSocket clients.
+
+    Parameters
+    ----------
+    agent_id:
+        The agent whose belief was revised.
+    endpoint:
+        Service / endpoint whose fault likelihood changed.
+    old_value:
+        Fault likelihood before the update.
+    new_value:
+        Fault likelihood after the update.
+    evidence:
+        The evidence value that triggered the update.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "belief_update",
+            "agent_id": agent_id,
+            "endpoint": endpoint,
+            "old_value": round(float(old_value), 4),
+            "new_value": round(float(new_value), 4),
+            "evidence": round(float(evidence), 4),
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast belief_update", exc_info=True)
+
+
+async def broadcast_usage_update(
+    tenant_id: str,
+    scan_type: str,
+    used: int,
+    limit: int,
+) -> None:
+    """Broadcast a ``usage_update`` message to all WebSocket clients.
+
+    Parameters
+    ----------
+    tenant_id:
+        The tenant whose usage changed.
+    scan_type:
+        ``"functional"`` or ``"security"``.
+    used:
+        New usage count after the latest scan.
+    limit:
+        The tenant's monthly quota for this scan type.
+    """
+    try:
+        percent = round(100.0 * used / limit, 2) if limit > 0 else 0.0
+        payload: Dict[str, Any] = {
+            "type": "usage_update",
+            "tenant_id": tenant_id,
+            "scan_type": scan_type,
+            "used": used,
+            "limit": limit,
+            "percent": percent,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast usage_update", exc_info=True)
+
+
+async def broadcast_usage_alert(
+    tenant_id: str,
+    scan_type: str,
+    used: int,
+    limit: int,
+) -> None:
+    """Broadcast a ``usage_alert`` message when a tenant approaches their quota.
+
+    Only sent when usage is at or above 80% of the monthly limit.  This is a
+    distinct event type from ``usage_update`` so the dashboard can surface a
+    visible upgrade nudge.
+
+    Parameters
+    ----------
+    tenant_id:
+        The tenant whose usage is near the limit.
+    scan_type:
+        ``"functional"`` or ``"security"``.
+    used:
+        Current usage count for the month.
+    limit:
+        The tenant's monthly quota for this scan type.
+    """
+    try:
+        percent = round(100.0 * used / limit, 1) if limit > 0 else 0.0
+        if percent < 80.0:
+            return
+        payload: Dict[str, Any] = {
+            "type": "usage_alert",
+            "tenant_id": tenant_id,
+            "scan_type": scan_type,
+            "used": used,
+            "limit": limit,
+            "percent": percent,
+            "message": (
+                f"You have used {percent}% of your monthly {scan_type} scan limit"
+            ),
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast usage_alert", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Registry accessor for the REST endpoint
+# ---------------------------------------------------------------------------
+
+
+def get_agent_snapshots() -> List[Dict[str, Any]]:
+    """Return the most-recent snapshot dict for every known agent."""
+    return list(_agent_registry.values())
+
+
+def clear_agent_registry() -> None:
+    """Clear the in-memory agent registry (useful for test isolation)."""
+    _agent_registry.clear()
+
+
+# ---------------------------------------------------------------------------
+# Team collaboration / Phase 10.4 broadcasts
+# ---------------------------------------------------------------------------
+
+
+async def broadcast_team_annotation(
+    finding_id: str,
+    author: str,
+    text: str,
+) -> None:
+    """Broadcast a ``team_annotation`` event when a user comments on a finding.
+
+    Parameters
+    ----------
+    finding_id:
+        Unique identifier of the finding being annotated.
+    author:
+        Display name or identifier of the user who added the comment.
+    text:
+        Comment body text.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "team_annotation",
+            "finding_id": finding_id,
+            "author": author,
+            "text": text,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast team_annotation", exc_info=True)
+
+
+async def broadcast_plan_generated(
+    plan_id: str,
+    endpoint_count: int,
+    scenario_count: int,
+) -> None:
+    """Broadcast a ``plan_generated`` event when an LLM test plan completes.
+
+    Parameters
+    ----------
+    plan_id:
+        Unique identifier of the generated test plan.
+    endpoint_count:
+        Number of API endpoints covered by the plan.
+    scenario_count:
+        Total number of test scenarios generated.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "plan_generated",
+            "plan_id": plan_id,
+            "endpoint_count": endpoint_count,
+            "scenario_count": scenario_count,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast plan_generated", exc_info=True)
+
+
+async def broadcast_schedule_fired(
+    schedule_id: str,
+    schedule_name: str,
+    scan_type: str,
+) -> None:
+    """Broadcast a ``schedule_fired`` event when a scheduled scan is triggered.
+
+    Parameters
+    ----------
+    schedule_id:
+        Unique identifier of the schedule that fired.
+    schedule_name:
+        Human-readable name of the schedule.
+    scan_type:
+        Type of scan triggered, e.g. ``"functional"`` or ``"security"``.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "schedule_fired",
+            "schedule_id": schedule_id,
+            "schedule_name": schedule_name,
+            "scan_type": scan_type,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast schedule_fired", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Discovery / Scenario Suggestion broadcasts (Phase 3)
+# ---------------------------------------------------------------------------
+
+
+async def broadcast_discovery_progress(
+    discovery_id: str,
+    pages_visited: int,
+    total_pages: int,
+    forms_found: int,
+) -> None:
+    """Broadcast a ``discovery_progress`` event to all WebSocket clients.
+
+    Parameters
+    ----------
+    discovery_id:
+        Unique identifier for the crawl run.
+    pages_visited:
+        Number of pages visited so far.
+    total_pages:
+        Total page budget for this crawl.
+    forms_found:
+        Number of forms discovered so far.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "discovery_progress",
+            "discovery_id": discovery_id,
+            "pages_visited": pages_visited,
+            "total_pages": total_pages,
+            "forms_found": forms_found,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast discovery_progress", exc_info=True)
+
+
+async def broadcast_discovery_complete(
+    discovery_id: str,
+    scenario_count: int,
+) -> None:
+    """Broadcast a ``discovery_complete`` event to all WebSocket clients.
+
+    Parameters
+    ----------
+    discovery_id:
+        Unique identifier for the completed crawl run.
+    scenario_count:
+        Number of scenarios generated.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "discovery_complete",
+            "discovery_id": discovery_id,
+            "scenario_count": scenario_count,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast discovery_complete", exc_info=True)
+
+
+async def broadcast_discovery_failed(
+    discovery_id: str,
+    error: str,
+) -> None:
+    """Broadcast a ``discovery_failed`` event to all WebSocket clients.
+
+    Parameters
+    ----------
+    discovery_id:
+        Unique identifier for the failed crawl run.
+    error:
+        Error message describing the failure.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "discovery_failed",
+            "discovery_id": discovery_id,
+            "error": error,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast discovery_failed", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Autonomous Test Loop broadcasts (Phase 5)
+# ---------------------------------------------------------------------------
+
+
+async def broadcast_autonomous_iteration(
+    run_id: str,
+    iteration: int,
+    passed: int,
+    failed: int,
+    flaky: int,
+    new_failures: int,
+    scenarios_executed: int,
+    coverage_pages: int,
+) -> None:
+    """Broadcast an ``autonomous_iteration`` event to all WebSocket clients.
+
+    Parameters
+    ----------
+    run_id:
+        Unique identifier for the autonomous run.
+    iteration:
+        Current iteration number.
+    passed:
+        Number of scenarios that passed in this iteration.
+    failed:
+        Number of scenarios that failed in this iteration.
+    flaky:
+        Number of flaky scenarios in this iteration.
+    new_failures:
+        Number of previously unseen failures discovered.
+    scenarios_executed:
+        Total scenarios executed in this iteration.
+    coverage_pages:
+        Cumulative unique pages tested so far.
+    """
+    try:
+        payload: Dict[str, Any] = {
+            "type": "autonomous_iteration",
+            "data": {
+                "run_id": run_id,
+                "iteration": iteration,
+                "passed": passed,
+                "failed": failed,
+                "flaky": flaky,
+                "new_failures": new_failures,
+                "scenarios_executed": scenarios_executed,
+                "coverage_pages": coverage_pages,
+            },
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast autonomous_iteration", exc_info=True)
+
+
+async def broadcast_autonomous_complete(
+    run_id: str,
+    stop_reason: str,
+    total_iterations: int,
+    total_passed: int,
+    total_failed: int,
+    delta: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Broadcast an ``autonomous_complete`` event to all WebSocket clients.
+
+    Parameters
+    ----------
+    run_id:
+        Unique identifier for the completed autonomous run.
+    stop_reason:
+        Why the loop stopped: ``"max_iterations"``, ``"max_duration"``,
+        ``"stable"``, ``"stopped"``, or ``"error"``.
+    total_iterations:
+        Total number of iterations completed.
+    total_passed:
+        Cumulative passed scenarios across all iterations.
+    total_failed:
+        Cumulative failed scenarios across all iterations.
+    delta:
+        Optional run-over-run delta summary dict produced by
+        :class:`~mannf.core.agents.autonomous_run_differ.AutonomousRunDiffer`.
+        When provided, clients receive richer delta fields such as
+        ``new_failure_count`` and ``resolved_failure_count``.
+    """
+    try:
+        data: Dict[str, Any] = {
+            "run_id": run_id,
+            "stop_reason": stop_reason,
+            "total_iterations": total_iterations,
+            "total_passed": total_passed,
+            "total_failed": total_failed,
+        }
+        if delta:
+            data["delta"] = delta
+        payload: Dict[str, Any] = {
+            "type": "autonomous_complete",
+            "data": data,
+            "timestamp": _now_iso(),
+        }
+        await _broadcast(payload)
+    except Exception:  # noqa: BLE001
+        logger.debug("Telemetry: failed to broadcast autonomous_complete", exc_info=True)