nat-engine 1__py3-none-any.whl

mannf/__init__.py

@@ -0,0 +1,33 @@
+# 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.
+
+"""
+MANNF – Multi-Agent Neural Network Framework
+for Adaptive Testing of Large-Scale Distributed Software Systems.
+
+Implements NeuroAgentTest (NAT) from the 1999 doctoral thesis by J. Brad
+Guider, adapted to modern Python using:
+  • asyncio for concurrent agent execution
+  • NumPy-based neural networks with backpropagation
+  • BDI (Belief–Desire–Intention) agent architecture
+  • Extended Contract Net Protocol (ECNP) for task coordination
+  • Dataclasses & type hints throughout
+"""
+
+from mannf.core.orchestrator import Orchestrator
+from mannf.core.nat_orchestrator import NATOrchestrator
+from mannf.core.testing.models import TestCase, TestResult, TestSuite
+from mannf.core.distributed.system_under_test import SystemUnderTest
+from mannf.core.agents.belief_state import BeliefState
+from mannf._version import __version__
+__all__ = [
+    "Orchestrator",
+    "NATOrchestrator",
+    "TestCase",
+    "TestResult",
+    "TestSuite",
+    "SystemUnderTest",
+    "BeliefState",
+]

mannf/__main__.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.
+
+"""Enable ``python -m mannf`` execution."""
+
+from mannf.cli import main
+
+main()

mannf/_version.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2026 NAT Contributors
+# 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.
+
+"""Single source of truth for the NAT package version."""
+
+__version__ = "1.0.0"

mannf/agents/__init__.py

@@ -0,0 +1,7 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents
+from mannf.core.agents import *  # noqa: F401, F403

mannf/agents/analyzer_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.analyzer_agent
+import sys
+import mannf.core.agents.analyzer_agent as _real
+sys.modules[__name__] = _real

mannf/agents/base.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.base
+import sys
+import mannf.core.agents.base as _real
+sys.modules[__name__] = _real

mannf/agents/bdi_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.bdi_agent
+import sys
+import mannf.core.agents.bdi_agent as _real
+sys.modules[__name__] = _real

mannf/agents/belief_state.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.belief_state
+import sys
+import mannf.core.agents.belief_state as _real
+sys.modules[__name__] = _real

mannf/agents/coordinator_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.coordinator_agent
+import sys
+import mannf.core.agents.coordinator_agent as _real
+sys.modules[__name__] = _real

mannf/agents/executor_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.executor_agent
+import sys
+import mannf.core.agents.executor_agent as _real
+sys.modules[__name__] = _real

mannf/agents/monitor_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.monitor_agent
+import sys
+import mannf.core.agents.monitor_agent as _real
+sys.modules[__name__] = _real

mannf/agents/oracle_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.oracle_agent
+import sys
+import mannf.core.agents.oracle_agent as _real
+sys.modules[__name__] = _real

mannf/agents/planner_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.planner_agent
+import sys
+import mannf.core.agents.planner_agent as _real
+sys.modules[__name__] = _real

mannf/agents/test_agent.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.agents.test_agent
+import sys
+import mannf.core.agents.test_agent as _real
+sys.modules[__name__] = _real

mannf/anomaly/__init__.py

@@ -0,0 +1,7 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.anomaly
+from mannf.core.anomaly import *  # noqa: F401, F403

mannf/anomaly/enhanced_detector.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.core.anomaly.enhanced_detector
+import sys
+import mannf.core.anomaly.enhanced_detector as _real
+sys.modules[__name__] = _real

mannf/cli.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Backward-compatible shim — source of truth has moved to mannf.product.cli
+import sys
+import mannf.product.cli as _real
+sys.modules[__name__] = _real

mannf/core/__init__.py

@@ -0,0 +1,26 @@
+# 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.
+
+"""
+NAT Core Engine — IP-protected algorithms and BDI/ECNP framework.
+"""
+
+from mannf.core.orchestrator import Orchestrator
+from mannf.core.nat_orchestrator import NATOrchestrator
+from mannf.core.testing.models import TestCase, TestResult, TestSuite
+from mannf.core.distributed.system_under_test import SystemUnderTest
+from mannf.core.agents.belief_state import BeliefState
+from mannf.core.reporting import UnifiedReportGenerator
+
+__all__ = [
+    "Orchestrator",
+    "NATOrchestrator",
+    "TestCase",
+    "TestResult",
+    "TestSuite",
+    "SystemUnderTest",
+    "BeliefState",
+    "UnifiedReportGenerator",
+]

mannf/core/agents/__init__.py

@@ -0,0 +1,52 @@
+# 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.
+
+"""Agents sub-package for the Multi-Agent Neural Network Framework."""
+
+from mannf.core.agents.base import BaseAgent
+from mannf.core.agents.bdi_agent import BDIAgent
+from mannf.core.agents.belief_state import BeliefState
+from mannf.core.agents.test_agent import TestAgent
+from mannf.core.agents.monitor_agent import MonitorAgent
+from mannf.core.agents.oracle_agent import OracleAgent
+from mannf.core.agents.planner_agent import PlannerAgent
+from mannf.core.agents.executor_agent import ExecutorAgent
+from mannf.core.agents.analyzer_agent import AnalyzerAgent
+from mannf.core.agents.coordinator_agent import CoordinatorAgent
+from mannf.core.agents.browser_executor_agent import BrowserExecutorAgent
+from mannf.core.agents.browser_coordinator_agent import BrowserCoordinatorAgent
+from mannf.core.agents.visual_regression_agent import VisualRegressionAgent
+from mannf.core.agents.accessibility_scanner_agent import AccessibilityScannerAgent
+from mannf.core.agents.performance_testing_agent import PerformanceTestingAgent
+from mannf.core.agents.web_crawler_agent import WebCrawlerAgent
+from mannf.core.agents.worker_pool import WorkerPool
+
+__all__ = [
+    "BaseAgent",
+    "BDIAgent",
+    "BeliefState",
+    # Original agents (backward-compat)
+    "TestAgent",
+    "MonitorAgent",
+    "OracleAgent",
+    # NAT BDI agents
+    "PlannerAgent",
+    "ExecutorAgent",
+    "AnalyzerAgent",
+    "CoordinatorAgent",
+    # Browser / Functional Testing agents
+    "BrowserExecutorAgent",
+    "BrowserCoordinatorAgent",
+    # Visual Regression
+    "VisualRegressionAgent",
+    # Accessibility Scanning
+    "AccessibilityScannerAgent",
+    # Performance Testing
+    "PerformanceTestingAgent",
+    # Web Crawler
+    "WebCrawlerAgent",
+    # Worker Pool
+    "WorkerPool",
+]

mannf/core/agents/accessibility_scanner_agent.py

@@ -0,0 +1,245 @@
+# 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.
+
+"""AccessibilityScannerAgent – BDI agent that audits page accessibility.
+
+Listens for :attr:`~mannf.core.messaging.messages.MessageType.DOM_SNAPSHOT`
+events published by browser agents, runs
+:func:`~mannf.core.browser.accessibility_scanner.scan_accessibility` against
+the registered :class:`~mannf.core.browser.dom_snapshot.DOMSnapshot`, and
+publishes :attr:`~MessageType.ACCESSIBILITY_SCAN_RESULT` with the findings.
+
+DOM snapshots must be deposited via :meth:`register_snapshot` before (or
+immediately after) the :attr:`~MessageType.DOM_SNAPSHOT` message arrives so
+the agent can retrieve them for analysis.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mannf.core.agents.bdi_agent import BDIAgent
+from mannf.core.browser.accessibility_scanner import (
+    AccessibilityScanResult,
+    scan_accessibility,
+)
+from mannf.core.browser.dom_snapshot import DOMSnapshot
+from mannf.core.messaging.bus import MessageBus
+from mannf.core.messaging.messages import Message, MessageType
+
+logger = logging.getLogger(__name__)
+
+
+class AccessibilityScannerAgent(BDIAgent):
+    """BDI agent that performs accessibility scanning on captured DOM snapshots.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier for this agent.
+    bus:
+        Shared message bus.
+    service_names:
+        Services in the system under test (forwarded to :class:`BDIAgent`).
+    min_compliance_score:
+        Minimum compliance percentage (0–100) below which a scan is considered
+        failing. Defaults to ``80.0``.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        bus: MessageBus,
+        service_names: list[str],
+        min_compliance_score: float = 80.0,
+    ) -> None:
+        super().__init__(agent_id=agent_id, bus=bus, service_names=service_names)
+
+        self._min_compliance_score = min_compliance_score
+
+        # url -> DOMSnapshot deposited by browser agents / orchestrator
+        self._snapshot_registry: dict[str, DOMSnapshot] = {}
+
+        # Scan results accumulated across all processed snapshots
+        self._scan_results: list[AccessibilityScanResult] = []
+
+    # ------------------------------------------------------------------
+    # BDIAgent contract
+    # ------------------------------------------------------------------
+
+    @property
+    def subscribed_types(self) -> set[MessageType]:
+        return {
+            MessageType.DOM_SNAPSHOT,
+            MessageType.INTERACTION_RESULT,
+            MessageType.BELIEF_UPDATE,
+        }
+
+    async def _handle_message(self, message: Message) -> None:
+        if message.type == MessageType.DOM_SNAPSHOT:
+            await self._on_dom_snapshot(message)
+        elif message.type == MessageType.INTERACTION_RESULT:
+            self._on_interaction_result(message)
+        elif message.type == MessageType.BELIEF_UPDATE:
+            payload = message.payload or {}
+            peer_beliefs = payload.get("beliefs", {})
+            if peer_beliefs:
+                self._absorb_peer_beliefs(message.sender_id, peer_beliefs)
+
+    # ------------------------------------------------------------------
+    # Snapshot registry
+    # ------------------------------------------------------------------
+
+    def register_snapshot(self, url: str, snapshot: DOMSnapshot) -> None:
+        """Deposit a :class:`DOMSnapshot` for the given URL.
+
+        The snapshot will be retrieved when a
+        :attr:`~MessageType.DOM_SNAPSHOT` message arrives for *url*.
+
+        Parameters
+        ----------
+        url:
+            The page URL the snapshot was captured from.
+        snapshot:
+            The :class:`DOMSnapshot` to store.
+        """
+        self._snapshot_registry[url] = snapshot
+
+    # ------------------------------------------------------------------
+    # Message handlers
+    # ------------------------------------------------------------------
+
+    async def _on_dom_snapshot(self, message: Message) -> None:
+        payload = message.payload or {}
+        url: str = payload.get("url", "")
+
+        snapshot = self._snapshot_registry.get(url)
+        if snapshot is None:
+            logger.debug(
+                "AccessibilityScannerAgent %s: no snapshot registered for %s — skipping",
+                self.agent_id, url,
+            )
+            return
+
+        await self._run_scan(url, snapshot)
+
+    def _on_interaction_result(self, message: Message) -> None:
+        # No-op — retained for symmetry with VisualRegressionAgent and to allow
+        # future enrichment (e.g. correlating scan results to test steps).
+        pass
+
+    # ------------------------------------------------------------------
+    # Core scanning logic
+    # ------------------------------------------------------------------
+
+    async def _run_scan(self, url: str, snapshot: DOMSnapshot) -> AccessibilityScanResult:
+        """Run the accessibility scan on *snapshot* and publish the result.
+
+        Parameters
+        ----------
+        url:
+            Page URL (used for logging and the published payload).
+        snapshot:
+            The :class:`DOMSnapshot` to audit.
+
+        Returns
+        -------
+        AccessibilityScanResult
+            The scan outcome (also stored internally for reporting).
+        """
+        result = scan_accessibility(snapshot)
+        self._scan_results.append(result)
+
+        passed = result.compliance_score >= self._min_compliance_score
+        logger.info(
+            "AccessibilityScannerAgent %s: url=%s violations=%d score=%.1f%% %s",
+            self.agent_id,
+            url,
+            result.violation_count,
+            result.compliance_score,
+            "PASS" if passed else "FAIL",
+        )
+
+        await self._publish(
+            Message(
+                MessageType.ACCESSIBILITY_SCAN_RESULT,
+                sender_id=self.agent_id,
+                payload={
+                    "url": url,
+                    "violation_count": result.violation_count,
+                    "compliance_score": result.compliance_score,
+                    "passed": passed,
+                    "violations": [
+                        {
+                            "rule_id": v.rule_id,
+                            "description": v.description,
+                            "impact": v.impact,
+                            "wcag_criteria": v.wcag_criteria,
+                            "selector": v.selector,
+                            "element_html": v.element_html,
+                        }
+                        for v in result.violations
+                    ],
+                },
+            )
+        )
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Reporting
+    # ------------------------------------------------------------------
+
+    def get_accessibility_report(self) -> dict[str, Any]:
+        """Return a summary of all accessibility scans performed.
+
+        Returns
+        -------
+        dict
+            ``{total_scans, passed, failed, avg_compliance_score,
+               results: [{url, violation_count, compliance_score, passed}...]}``
+        """
+        total = len(self._scan_results)
+        passed_count = sum(
+            1 for r in self._scan_results
+            if r.compliance_score >= self._min_compliance_score
+        )
+        failed_count = total - passed_count
+        avg_score = (
+            round(
+                sum(r.compliance_score for r in self._scan_results) / total,
+                1,
+            )
+            if total > 0
+            else 100.0
+        )
+
+        return {
+            "total_scans": total,
+            "passed": passed_count,
+            "failed": failed_count,
+            "avg_compliance_score": avg_score,
+            "results": [
+                {
+                    "url": r.url,
+                    "violation_count": r.violation_count,
+                    "compliance_score": r.compliance_score,
+                    "passed": r.compliance_score >= self._min_compliance_score,
+                    "violations": [
+                        {
+                            "rule_id": v.rule_id,
+                            "description": v.description,
+                            "impact": v.impact,
+                            "wcag_criteria": v.wcag_criteria,
+                            "selector": v.selector,
+                            "element_html": v.element_html,
+                        }
+                        for v in r.violations
+                    ],
+                }
+                for r in self._scan_results
+            ],
+        }