nat-engine 1__py3-none-any.whl

mannf/core/agents/coordinator_agent.py

@@ -0,0 +1,262 @@
+# 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.
+
+"""Coordinator Agent – implements the Extended Contract Net Protocol (ECNP).
+
+The CoordinatorAgent receives TASK_ANNOUNCEMENT messages from PlannerAgents,
+collects bids from ExecutorAgents over a configurable time window, evaluates
+bids incorporating learned risk estimates, and awards contracts to the winning
+bidder (Thesis §4.4).
+
+ECNP cycle (per task):
+  1. Receive TASK_ANNOUNCEMENT from PlannerAgent.
+  2. Re-broadcast as announcement to ExecutorAgents (on TASK_ANNOUNCEMENT bus).
+  3. Collect TASK_BID messages during the bid window (``bid_timeout_s``).
+  4. Select winner: highest ``bid_value × risk_modulator``.
+  5. Publish CONTRACT_AWARD to the winning agent.
+  6. Wait for CONTRACT_RESULT; broadcast to PlannerAgents and AnalyzerAgents.
+
+Safeguards (Thesis Appendix A.3):
+  * Renegotiation threshold: a task is re-announced if no bids arrive.
+  * Coordination rotation: coordinators can hand off if overloaded.
+  * Duplicate-contract prevention via task_id tracking.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import defaultdict
+from typing import Any, Dict, List, Optional, Set
+
+from mannf.core.agents.bdi_agent import BDIAgent
+from mannf.core.messaging.bus import MessageBus
+from mannf.core.messaging.messages import Message, MessageType
+
+logger = logging.getLogger(__name__)
+
+
+class CoordinatorAgent(BDIAgent):
+    """Allocates testing tasks via the Extended Contract Net Protocol.
+
+    Parameters
+    ----------
+    bid_timeout_s:
+        How long (seconds) to wait for bids before awarding or re-announcing.
+    max_renegotiations:
+        Maximum times a task is re-announced if no bids arrive.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        bus: MessageBus,
+        service_names: List[str],
+        bid_timeout_s: float = 0.05,
+        max_renegotiations: int = 2,
+    ) -> None:
+        super().__init__(agent_id, bus, service_names)
+        self._bid_timeout_s = bid_timeout_s
+        self._max_renegotiations = max_renegotiations
+
+        # Pending bids: task_id → list of bid payloads
+        self._pending_bids: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+        # Awarded tasks: task_id → winner_id (prevent duplicates)
+        self._awarded: Dict[str, str] = {}
+        # Re-announcement counters
+        self._renegotiation_counts: Dict[str, int] = defaultdict(int)
+
+        # Statistics
+        self._contracts_awarded = 0
+        self._contracts_completed = 0
+
+    @property
+    def subscribed_types(self) -> Set[MessageType]:
+        return {
+            MessageType.TASK_ANNOUNCEMENT,
+            MessageType.TASK_BID,
+            MessageType.CONTRACT_RESULT,
+            MessageType.BELIEF_UPDATE,
+        }
+
+    # ------------------------------------------------------------------
+    # Message handling
+    # ------------------------------------------------------------------
+
+    async def _handle_message(self, message: Message) -> None:
+        if message.type == MessageType.TASK_ANNOUNCEMENT:
+            await self._handle_announcement(message)
+        elif message.type == MessageType.TASK_BID:
+            self._handle_bid(message)
+        elif message.type == MessageType.CONTRACT_RESULT:
+            await self._handle_contract_result(message)
+        elif message.type == MessageType.BELIEF_UPDATE:
+            self._absorb_peer_beliefs(
+                message.sender_id,
+                message.payload.get("beliefs", {}),
+            )
+
+    # ------------------------------------------------------------------
+    # ECNP: announcement phase
+    # ------------------------------------------------------------------
+
+    async def _handle_announcement(self, message: Message) -> None:
+        """Receive task from PlannerAgent and open bid collection."""
+        # Ignore own re-broadcasts to prevent infinite loops
+        if message.sender_id == self.agent_id:
+            return
+
+        task = message.payload or {}
+        task_id = task.get("task_id")
+        if not task_id or task_id in self._awarded:
+            return
+        # Deduplicate: ignore if already being processed
+        if task_id in self._pending_bids or task_id in self._renegotiation_counts:
+            return
+
+        # Re-broadcast the announcement so ExecutorAgents see it
+        await self._publish(
+            Message(MessageType.TASK_ANNOUNCEMENT, self.agent_id, task)
+        )
+
+        # Emit ECNP "offer" telemetry event (fail-safe)
+        try:
+            from mannf.dashboard import telemetry as _tel
+            await _tel.broadcast_ecnp_event(
+                event_kind="offer",
+                sender_id=self.agent_id,
+                contract_id=task_id,
+                details={
+                    "target": task.get("target", ""),
+                    "priority": task.get("priority", 0.0),
+                    "risk_estimate": task.get("risk_estimate", 0.0),
+                    "planner_id": task.get("planner_id", ""),
+                },
+            )
+        except Exception:  # noqa: BLE001
+            pass
+
+        # Wait for bids then award
+        asyncio.get_running_loop().create_task(
+            self._award_after_timeout(task)
+        )
+
+    # ------------------------------------------------------------------
+    # ECNP: bid collection
+    # ------------------------------------------------------------------
+
+    def _handle_bid(self, message: Message) -> None:
+        bid = message.payload or {}
+        task_id = bid.get("task_id")
+        if task_id and task_id not in self._awarded:
+            self._pending_bids[task_id].append(bid)
+            logger.debug(
+                "CoordinatorAgent %s: received bid %.3f from %s for task %s",
+                self.agent_id, bid.get("bid_value", 0.0),
+                bid.get("bidder_id", "?"), task_id,
+            )
+
+    # ------------------------------------------------------------------
+    # ECNP: award phase
+    # ------------------------------------------------------------------
+
+    async def _award_after_timeout(self, task: Dict[str, Any]) -> None:
+        """Wait for bid_timeout, then award to highest bidder."""
+        await asyncio.sleep(self._bid_timeout_s)
+
+        task_id = task.get("task_id")
+        if not task_id or task_id in self._awarded:
+            return
+
+        bids = self._pending_bids.pop(task_id, [])
+        if not bids:
+            # No bids – renegotiate if allowed
+            count = self._renegotiation_counts[task_id]
+            if count < self._max_renegotiations:
+                self._renegotiation_counts[task_id] = count + 1
+                logger.debug(
+                    "CoordinatorAgent %s: no bids for task %s; re-announcing (%d/%d)",
+                    self.agent_id, task_id, count + 1, self._max_renegotiations,
+                )
+                await self._publish(
+                    Message(MessageType.TASK_ANNOUNCEMENT, self.agent_id, task)
+                )
+                asyncio.get_running_loop().create_task(
+                    self._award_after_timeout(task)
+                )
+            return
+
+        # Select winner: highest bid_value (risk-modulated)
+        winner_bid = max(bids, key=lambda b: b.get("bid_value", 0.0))
+        winner_id = winner_bid.get("bidder_id", "")
+
+        self._awarded[task_id] = winner_id
+        self._contracts_awarded += 1
+
+        contract = {
+            **task,
+            "winner_id": winner_id,
+            "winning_bid": winner_bid.get("bid_value", 0.0),
+        }
+        await self._publish(
+            Message(MessageType.CONTRACT_AWARD, self.agent_id, contract)
+        )
+        logger.debug(
+            "CoordinatorAgent %s: awarded task %s to %s (bid=%.3f)",
+            self.agent_id, task_id, winner_id, winner_bid.get("bid_value", 0.0),
+        )
+
+        # Emit ECNP "award" telemetry event (fail-safe)
+        try:
+            from mannf.dashboard import telemetry as _tel
+            await _tel.broadcast_ecnp_event(
+                event_kind="award",
+                sender_id=self.agent_id,
+                contract_id=task_id,
+                details={
+                    "winner_id": winner_id,
+                    "winning_bid": winner_bid.get("bid_value", 0.0),
+                    "target": task.get("target", ""),
+                    "all_bids": [
+                        {"bidder_id": b.get("bidder_id"), "bid_value": b.get("bid_value", 0.0)}
+                        for b in bids
+                    ],
+                },
+            )
+        except Exception:  # noqa: BLE001
+            pass
+
+    # ------------------------------------------------------------------
+    # ECNP: completion
+    # ------------------------------------------------------------------
+
+    async def _handle_contract_result(self, message: Message) -> None:
+        """Process execution outcome and update own beliefs.
+
+        Planners and Analyzers already subscribe directly to CONTRACT_RESULT
+        from Executors, so we don't re-broadcast to avoid message storms.
+        """
+        payload = message.payload or {}
+        self._contracts_completed += 1
+
+        # Update own beliefs based on outcome
+        target = payload.get("target", "")
+        if target:
+            passed = payload.get("passed", True)
+            error = payload.get("error")
+            evidence = 0.0 if passed else (0.5 if error else 1.0)
+            self._update_belief_from_result(target, evidence)
+
+    # ------------------------------------------------------------------
+    # Diagnostics
+    # ------------------------------------------------------------------
+
+    @property
+    def contracts_awarded(self) -> int:
+        return self._contracts_awarded
+
+    @property
+    def contracts_completed(self) -> int:
+        return self._contracts_completed

mannf/core/agents/executor_agent.py

@@ -0,0 +1,222 @@
+# 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.
+
+"""Executor Agent – executes test cases awarded by the CoordinatorAgent.
+
+The ExecutorAgent receives CONTRACT_AWARD messages, executes the requested
+test against the system under test, and publishes CONTRACT_RESULT messages
+back to the coordinator (Thesis §4.2).
+
+Bidding model (ECNP §4.4):
+  * Bid value = expected informational gain, computed as:
+      bid = own_fault_belief[target] × (1 − recent_execution_load)
+  * Higher fault belief + lower load → higher bid → more likely to win.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import string
+import uuid
+from collections import deque
+from typing import Any, Deque, Dict, List, Optional, Set
+
+import numpy as np
+
+from mannf.core.agents.bdi_agent import BDIAgent
+from mannf.core.distributed.system_under_test import SystemUnderTest
+from mannf.core.messaging.bus import MessageBus
+from mannf.core.messaging.messages import Message, MessageType
+from mannf.core.testing.models import TestCase, TestResult
+
+logger = logging.getLogger(__name__)
+
+_LOAD_WINDOW = 10  # sliding window for execution load estimation
+
+
+class ExecutorAgent(BDIAgent):
+    """Executes test cases through ECNP contract bidding.
+
+    Parameters
+    ----------
+    sut:
+        The system under test to execute against.
+    max_concurrent:
+        Maximum simultaneous executions (backpressure signal to bids).
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        bus: MessageBus,
+        service_names: List[str],
+        sut: SystemUnderTest,
+        max_concurrent: int = 3,
+    ) -> None:
+        super().__init__(agent_id, bus, service_names)
+        self._sut = sut
+        self._max_concurrent = max_concurrent
+        self._active: int = 0
+        self._latency_window: Deque[float] = deque(maxlen=_LOAD_WINDOW)
+        self._executions = 0
+
+    @property
+    def subscribed_types(self) -> Set[MessageType]:
+        return {
+            MessageType.TASK_ANNOUNCEMENT,  # evaluate and potentially bid
+            MessageType.CONTRACT_AWARD,     # execute if we won
+            MessageType.BELIEF_UPDATE,      # absorb peer beliefs
+        }
+
+    # ------------------------------------------------------------------
+    # Message handling
+    # ------------------------------------------------------------------
+
+    async def _handle_message(self, message: Message) -> None:
+        if message.type == MessageType.TASK_ANNOUNCEMENT:
+            await self._evaluate_and_bid(message)
+        elif message.type == MessageType.CONTRACT_AWARD:
+            if message.payload.get("winner_id") == self.agent_id:
+                await self._execute_contract(message.payload)
+        elif message.type == MessageType.BELIEF_UPDATE:
+            self._absorb_peer_beliefs(
+                message.sender_id,
+                message.payload.get("beliefs", {}),
+            )
+
+    # ------------------------------------------------------------------
+    # ECNP bidding
+    # ------------------------------------------------------------------
+
+    async def _evaluate_and_bid(self, announcement: Message) -> None:
+        """Compute a bid value and submit it to the CoordinatorAgent."""
+        task = announcement.payload or {}
+        target = task.get("target", "")
+        if not target:
+            return
+
+        # Bid = fault-likelihood belief × availability factor
+        fault_belief = self.beliefs.fault_likelihood.get(target, 0.5)
+        load_factor = 1.0 - (self._active / max(self._max_concurrent, 1))
+        bid_value = fault_belief * max(0.1, load_factor)
+
+        await self._publish(
+            Message(
+                MessageType.TASK_BID,
+                sender_id=self.agent_id,
+                payload={
+                    "task_id": task.get("task_id"),
+                    "target": target,
+                    "bid_value": bid_value,
+                    "bidder_id": self.agent_id,
+                },
+                correlation_id=announcement.id,
+            )
+        )
+        logger.debug(
+            "ExecutorAgent %s: bid %.3f for %s",
+            self.agent_id, bid_value, target,
+        )
+
+        # Emit ECNP "bid" telemetry event (fail-safe)
+        try:
+            from mannf.dashboard import telemetry as _tel
+            await _tel.broadcast_ecnp_event(
+                event_kind="bid",
+                sender_id=self.agent_id,
+                contract_id=task.get("task_id", ""),
+                details={
+                    "target": target,
+                    "bid_value": round(bid_value, 4),
+                    "load_factor": round(max(0.1, load_factor), 4),
+                    "fault_belief": round(fault_belief, 4),
+                },
+            )
+        except Exception:  # noqa: BLE001
+            pass
+
+    # ------------------------------------------------------------------
+    # Contract execution
+    # ------------------------------------------------------------------
+
+    async def _execute_contract(self, contract: Dict[str, Any]) -> None:
+        """Execute the awarded test contract against the SUT."""
+        target = contract.get("target", "")
+        if not target:
+            return
+
+        self._active += 1
+        test_case = self._build_test_case(target, contract)
+
+        try:
+            result = await self._sut.execute(test_case)
+            result.agent_id = self.agent_id
+            self._executions += 1
+
+            # Update own beliefs based on outcome
+            evidence = 0.0 if result.passed else (0.5 if result.error else 1.0)
+            self._update_belief_from_result(target, evidence)
+
+            if result.execution_time_ms:
+                self._latency_window.append(result.execution_time_ms)
+
+            # Publish result back to the bus (monitor/oracle listen)
+            await self._publish(
+                Message(
+                    MessageType.TEST_RESULT,
+                    sender_id=self.agent_id,
+                    payload={"result": result, "test_case": test_case},
+                )
+            )
+            # Notify coordinator of completion
+            await self._publish(
+                Message(
+                    MessageType.CONTRACT_RESULT,
+                    sender_id=self.agent_id,
+                    payload={
+                        "task_id": contract.get("task_id"),
+                        "target": target,
+                        "passed": result.passed,
+                        "error": result.error,
+                        "execution_time_ms": result.execution_time_ms,
+                        "executor_id": self.agent_id,
+                        "test_case": test_case,
+                        "result": result,
+                    },
+                    correlation_id=contract.get("task_id"),
+                )
+            )
+            logger.debug(
+                "ExecutorAgent %s: executed %s → %s",
+                self.agent_id, target, "PASS" if result.passed else "FAIL",
+            )
+        finally:
+            self._active -= 1
+
+    @staticmethod
+    def _build_test_case(target: str, contract: Dict[str, Any]) -> TestCase:
+        inputs = {
+            "request_id": str(uuid.uuid4()),
+            "user_id": random.randint(1, 10_000),
+            "action": random.choice(["create", "read", "update", "delete"]),
+            "auth_token": "".join(random.choices(string.ascii_letters, k=16)),
+            "payload_size": random.randint(1, 1024),
+        }
+        return TestCase(
+            target=target,
+            inputs=inputs,
+            expected_behavior=f"Service {target!r} returns a successful response",
+            priority=contract.get("risk_estimate", 0.5),
+            metadata={"task_id": contract.get("task_id", ""), "executor": contract.get("winner_id", "")},
+        )
+
+    @property
+    def execution_count(self) -> int:
+        return self._executions
+
+    @property
+    def avg_latency_ms(self) -> float:
+        return float(np.mean(list(self._latency_window))) if self._latency_window else 0.0

mannf/core/agents/monitor_agent.py

@@ -0,0 +1,188 @@
+# 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.
+
+"""Monitor agent.
+
+The :class:`MonitorAgent` collects execution metrics from
+:class:`TestResult` messages and uses an anomaly-detection neural network
+to flag unusual system behaviour.  It publishes
+:attr:`MessageType.METRICS_UPDATE` and :attr:`MessageType.ANOMALY_DETECTED`
+messages that other agents can react to.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import deque
+from typing import Any, Deque, Dict, List, Optional, Set, Tuple
+
+import numpy as np
+
+from mannf.core.agents.base import BaseAgent
+from mannf.core.messaging.bus import MessageBus
+from mannf.core.messaging.messages import Message, MessageType
+from mannf.core.neural import NeuralNetwork
+from mannf.core.testing.models import TestResult
+
+logger = logging.getLogger(__name__)
+
+_METRIC_DIM = 6   # dimensionality of the metric feature vector
+_HISTORY = 50     # sliding window length for anomaly detection baseline
+
+
+class MonitorAgent(BaseAgent):
+    """Monitors test execution metrics and detects anomalies.
+
+    The agent maintains a sliding window of recent test results and trains
+    an autoencoder-style anomaly detector: inputs ≈ outputs when normal;
+    high reconstruction error signals an anomaly.
+    """
+
+    def __init__(self, agent_id: str, bus: MessageBus) -> None:
+        # Autoencoder: compress 6-D metrics to 3-D then reconstruct
+        network = NeuralNetwork(
+            layer_sizes=[_METRIC_DIM, 12, 3, 12, _METRIC_DIM],
+            hidden_activation="relu",
+            learning_rate=0.005,
+        )
+        super().__init__(agent_id, bus, network)
+
+        self._history: Deque[np.ndarray] = deque(maxlen=_HISTORY)
+        self._total_tests = 0
+        self._total_failures = 0
+        self._total_errors = 0
+        self._latency_window: Deque[float] = deque(maxlen=_HISTORY)
+
+        # Dynamic threshold for anomaly detection (updated per batch)
+        self._anomaly_threshold: float = 1.0
+
+    @property
+    def subscribed_types(self) -> Set[MessageType]:
+        return {MessageType.TEST_RESULT}
+
+    # ------------------------------------------------------------------
+    # Message handling
+    # ------------------------------------------------------------------
+
+    async def _handle_message(self, message: Message) -> None:
+        if message.type == MessageType.TEST_RESULT:
+            payload = message.payload
+            result: TestResult = (
+                payload.get("result") if isinstance(payload, dict) else payload
+            )
+            if isinstance(result, TestResult):
+                self._ingest(result)
+
+    async def _on_idle(self) -> None:
+        """Periodically broadcast a metrics snapshot."""
+        if self._total_tests > 0:
+            snapshot = self._metrics_snapshot()
+            await self._publish(
+                Message(MessageType.METRICS_UPDATE, self.agent_id, snapshot)
+            )
+
+    # ------------------------------------------------------------------
+    # Metric ingestion and anomaly detection
+    # ------------------------------------------------------------------
+
+    def _ingest(self, result: TestResult) -> None:
+        self._total_tests += 1
+        if result.error:
+            self._total_errors += 1
+        elif not result.passed:
+            self._total_failures += 1
+        self._latency_window.append(result.execution_time_ms)
+
+        vec = self._result_to_vector(result)
+        self._history.append(vec)
+
+        # Train autoencoder on normal data (passed tests only)
+        if result.passed and not result.error and self.network is not None:
+            self.network.train_step(vec, vec)
+
+        # Check for anomaly once we have a baseline
+        if len(self._history) >= 10:
+            self._check_anomaly(result, vec)
+
+    def _result_to_vector(self, result: TestResult) -> np.ndarray:
+        """Encode a TestResult into a fixed-size numeric vector."""
+        vec = np.zeros(_METRIC_DIM)
+        vec[0] = 1.0 if result.passed else 0.0
+        vec[1] = 1.0 if result.error else 0.0
+        vec[2] = min(result.execution_time_ms / 1000.0, 5.0)  # cap at 5 s
+        vec[3] = self._failure_rate()
+        vec[4] = self._error_rate()
+        vec[5] = self._avg_latency() / 1000.0
+        return vec
+
+    def _check_anomaly(self, result: TestResult, vec: np.ndarray) -> None:
+        """Use the autoencoder reconstruction error to detect anomalies."""
+        assert self.network is not None
+        recon = self.network.predict(vec)
+        error = float(np.mean((vec - recon) ** 2))
+
+        # Update threshold as 2× median of recent reconstruction errors
+        recent_errors = [
+            float(np.mean((v - self.network.predict(v)) ** 2))
+            for v in list(self._history)[-20:]
+        ]
+        if recent_errors:
+            self._anomaly_threshold = max(2.0 * float(np.median(recent_errors)), 1e-6)
+
+        if error > self._anomaly_threshold:
+            logger.info(
+                "MonitorAgent %s: anomaly detected (error=%.4f > threshold=%.4f)",
+                self.agent_id, error, self._anomaly_threshold,
+            )
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(
+                    self._publish(
+                        Message(
+                            MessageType.ANOMALY_DETECTED,
+                            self.agent_id,
+                            {
+                                "test_case_id": result.test_case_id,
+                                "reconstruction_error": error,
+                                "threshold": self._anomaly_threshold,
+                            },
+                        )
+                    )
+                )
+            except RuntimeError:
+                pass  # No running event loop; skip async publish
+
+    # ------------------------------------------------------------------
+    # Statistics helpers
+    # ------------------------------------------------------------------
+
+    def _failure_rate(self) -> float:
+        return self._total_failures / self._total_tests if self._total_tests else 0.0
+
+    def _error_rate(self) -> float:
+        return self._total_errors / self._total_tests if self._total_tests else 0.0
+
+    def _avg_latency(self) -> float:
+        if not self._latency_window:
+            return 0.0
+        return float(np.mean(list(self._latency_window)))
+
+    def _metrics_snapshot(self) -> Dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "total_tests": self._total_tests,
+            "total_failures": self._total_failures,
+            "total_errors": self._total_errors,
+            "failure_rate": round(self._failure_rate(), 4),
+            "error_rate": round(self._error_rate(), 4),
+            "avg_latency_ms": round(self._avg_latency(), 2),
+            "anomaly_threshold": round(self._anomaly_threshold, 6),
+        }
+
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        return self._metrics_snapshot()
+