nat-engine 1__py3-none-any.whl

mannf/core/agents/bdi_agent.py

@@ -0,0 +1,330 @@
+# 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.
+
+"""BDI (Belief–Desire–Intention) agent base class.
+
+Extends :class:`BaseAgent` with explicit BDI mental state as described in
+Chapter 3 of the NeuroAgentTest thesis:
+
+  * **Beliefs** – probabilistic fault-likelihood estimates per service
+    (managed by :class:`BeliefState`).
+  * **Desires** – high-level testing objectives (e.g. maximise coverage,
+    isolate defects) represented as weighted goal dictionaries.
+  * **Intentions** – concrete, committed action plans drawn from the
+    deliberation cycle.
+
+Each BDI agent owns *two* neural networks (Thesis §3.2):
+  * ``predictor_net`` – maps static feature vectors to fault-proneness scores.
+  * ``oracle_net``    – maps execution-trace features to anomaly scores.
+
+The deliberation cycle runs every time the inbox is drained, calling
+:meth:`_deliberate` to revise intentions based on updated beliefs.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import abstractmethod
+from typing import Any, Dict, List, Optional, Set
+
+from mannf.core.agents.base import BaseAgent
+from mannf.core.agents.belief_state import BeliefState
+from mannf.core.messaging.bus import MessageBus
+from mannf.core.messaging.messages import Message, MessageType
+from mannf.core.neural import NeuralNetwork
+
+logger = logging.getLogger(__name__)
+
+# Feature dimensions (must match what each network was built with)
+_PREDICTOR_IN = 8    # static code-metric features
+_ORACLE_IN = 6       # runtime execution-trace features
+_HIDDEN = 16
+
+
+class BDIAgent(BaseAgent):
+    """Agent with explicit BDI mental state and dual neural networks.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier.
+    bus:
+        Shared message bus.
+    service_names:
+        All services in the system under test.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        bus: MessageBus,
+        service_names: List[str],
+    ) -> None:
+        # --- Beliefs -------------------------------------------------------
+        self.beliefs = BeliefState(services=service_names)
+
+        # --- Desires -------------------------------------------------------
+        # Weighted objective dictionary; subclasses may override
+        self.desires: Dict[str, float] = {
+            "maximise_coverage": 1.0,
+            "isolate_defects": 1.5,
+            "reduce_redundancy": 0.8,
+        }
+
+        # --- Intentions ----------------------------------------------------
+        # Current committed action plan (list of (action, args) tuples)
+        self.intentions: List[Dict[str, Any]] = []
+
+        # --- Neural networks -----------------------------------------------
+        n_services = max(len(service_names), 1)
+        # Predictor: static metrics → per-service fault-proneness scores
+        self.predictor_net = NeuralNetwork(
+            layer_sizes=[_PREDICTOR_IN, _HIDDEN, _HIDDEN, n_services],
+            hidden_activation="relu",
+            learning_rate=0.008,
+        )
+        # Oracle: runtime traces → anomaly score (single output)
+        self.oracle_net = NeuralNetwork(
+            layer_sizes=[_ORACLE_IN, _HIDDEN, _HIDDEN // 2, 1],
+            hidden_activation="relu",
+            learning_rate=0.005,
+        )
+
+        # Pass None as the single "network" to BaseAgent (we manage ours)
+        super().__init__(agent_id, bus, network=None)
+
+    # ------------------------------------------------------------------
+    # BDI deliberation cycle
+    # ------------------------------------------------------------------
+
+    async def _on_idle(self) -> None:
+        """Runs each idle cycle – triggers the deliberation step."""
+        self._deliberate()
+
+    def _deliberate(self) -> None:
+        """Revise intentions based on current beliefs and desires.
+
+        Generates a prioritised action list using the Predictor network to
+        score each service, then filters by desire weights.
+        """
+        import numpy as np
+
+        # Build feature vector for the Predictor network
+        x = self._build_predictor_features()
+        scores = self.predictor_net.predict(x)
+
+        # Blend NN scores with belief-state likelihoods (bounded by conf)
+        blended: List[tuple[str, float]] = []
+        for i, svc in enumerate(self.beliefs.services):
+            nn_score = float(scores[i]) if i < len(scores) else 0.0
+            belief = self.beliefs.fault_likelihood.get(svc, 0.5)
+            conf = self.beliefs.confidence.get(svc, 0.0)
+            # Weighted blend: high confidence → trust beliefs more
+            blended_score = conf * belief + (1.0 - conf) * max(0.0, nn_score)
+            blended.append((svc, blended_score))
+
+        # Apply desire weights
+        isolate_weight = self.desires.get("isolate_defects", 1.0)
+        blended.sort(key=lambda t: t[1] * isolate_weight, reverse=True)
+
+        # Enforce exploration quota: inject low-belief services if entropy too low
+        if self.beliefs.exploration_deficit() > 0:
+            prioritised = self.beliefs.prioritise()
+            # Move the last entry to the front as an exploration push
+            if len(prioritised) > 1:
+                blended.insert(0, (prioritised[-1], 0.0))
+
+        self.intentions = [{"action": "test", "target": svc, "score": sc} for svc, sc in blended]
+
+        # Schedule agent-state telemetry broadcast (non-blocking, fail-safe)
+        try:
+            import asyncio
+            from mannf.dashboard import telemetry as _tel
+            loop = asyncio.get_running_loop()
+            loop.create_task(_tel.broadcast_agent_state(self))
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _build_predictor_features(self) -> "np.ndarray":
+        """Build the 8-D static feature vector fed into the Predictor network."""
+        import numpy as np
+
+        vec = np.zeros(_PREDICTOR_IN)
+        beliefs = list(self.beliefs.fault_likelihood.values())
+        if beliefs:
+            vec[0] = float(np.mean(beliefs))
+            vec[1] = float(np.std(beliefs)) if len(beliefs) > 1 else 0.0
+            vec[2] = float(np.max(beliefs))
+            vec[3] = float(np.min(beliefs))
+        vec[4] = self.beliefs.entropy()
+        vec[5] = float(len(self.beliefs.services)) / 20.0
+        # Desire weights
+        vec[6] = self.desires.get("isolate_defects", 1.0) / 2.0
+        vec[7] = self.desires.get("maximise_coverage", 1.0) / 2.0
+        return vec
+
+    # ------------------------------------------------------------------
+    # Belief revision helpers
+    # ------------------------------------------------------------------
+
+    def _update_belief_from_result(self, service: str, evidence: float) -> None:
+        """Update fault-likelihood belief and retrain the Predictor network."""
+        import numpy as np
+
+        self.beliefs.update(service, evidence)
+
+        # Train Predictor to align with updated beliefs
+        x = self._build_predictor_features()
+        target = np.array([self.beliefs.fault_likelihood.get(s, 0.5) for s in self.beliefs.services])
+        self.predictor_net.train_step(x, target)
+
+    def _update_belief_from_user_feedback(self, service: str) -> None:
+        """Incorporate a user-dismissed finding as a false-positive (FP) signal.
+
+        Injects ``evidence=0.0`` to recalibrate the belief downward and
+        retrains the Predictor network so that future deliberation reflects
+        the corrected signal.
+
+        Parameters
+        ----------
+        service:
+            Endpoint key (e.g. ``"POST /api/v1/login"``) whose finding was
+            dismissed by the user as a false positive.
+        """
+        self._update_belief_from_result(service, 0.0)
+
+    def _score_anomaly(self, trace_features: "np.ndarray") -> float:
+        """Use the Oracle network to score an execution trace for anomaly."""
+        return float(self.oracle_net.predict(trace_features)[0])
+
+    # ------------------------------------------------------------------
+    # Broadcast own beliefs to peers
+    # ------------------------------------------------------------------
+
+    async def _broadcast_beliefs(self) -> None:
+        from mannf.core.messaging.messages import Message, MessageType
+
+        await self._publish(
+            Message(
+                MessageType.BELIEF_UPDATE,
+                sender_id=self.agent_id,
+                payload={
+                    "beliefs": self.beliefs.snapshot(),
+                    "entropy": self.beliefs.entropy(),
+                },
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Incorporate peer beliefs
+    # ------------------------------------------------------------------
+
+    def _absorb_peer_beliefs(self, peer_id: str, peer_beliefs: Dict[str, float]) -> None:
+        """Merge peer belief snapshot into own beliefs (confidence-weighted)."""
+        for svc, peer_val in peer_beliefs.items():
+            own_val = self.beliefs.fault_likelihood.get(svc, 0.5)
+            own_conf = self.beliefs.confidence.get(svc, 0.0)
+            # Weight peer evidence inversely to own confidence
+            weight = 0.5 * (1.0 - own_conf)
+            blended = own_val + weight * (peer_val - own_val)
+            self.beliefs.fault_likelihood[svc] = max(0.01, min(0.99, blended))
+
+    # ------------------------------------------------------------------
+    # Weight persistence helpers
+    # ------------------------------------------------------------------
+
+    def save_weights(self) -> Dict[str, Any]:
+        """Return a serialisable snapshot of this agent's network weights.
+
+        Returns
+        -------
+        dict
+            ``{"role": str, "layers": List[dict]}`` where each layer dict
+            contains ``{"W": List, "b": List}`` (numpy arrays converted via
+            ``.tolist()``).
+        """
+        layers = []
+        for net_name in ("predictor_net", "oracle_net"):
+            net = getattr(self, net_name, None)
+            if net is not None:
+                for wb in net.get_weights():
+                    layers.append({"net": net_name, "W": wb["W"].tolist(), "b": wb["b"].tolist()})
+        return {"role": self.__class__.__name__.lower().replace("agent", ""), "layers": layers}
+
+    def load_weights(self, snapshot: Dict[str, Any]) -> None:
+        """Restore network weights from a previously saved snapshot.
+
+        Incompatible shapes are silently skipped with a warning so that a
+        partially-compatible snapshot does not crash the agent.
+
+        Parameters
+        ----------
+        snapshot:
+            Dict as returned by :meth:`save_weights` (``{"layers": [...]}``)
+            or the ``{"W": ndarray, "b": ndarray}`` layer format used by
+            :meth:`~mannf.core.neural.NeuralNetwork.set_weights`.
+        """
+        import numpy as np
+
+        layers_raw = snapshot.get("layers", [])
+
+        # Group layers back by network name
+        predictor_layers: List[Dict[str, Any]] = []
+        oracle_layers: List[Dict[str, Any]] = []
+
+        for layer in layers_raw:
+            net_name = layer.get("net", "")
+            entry = {
+                "W": np.array(layer["W"], dtype=float) if not isinstance(layer["W"], np.ndarray) else layer["W"],
+                "b": np.array(layer["b"], dtype=float) if not isinstance(layer["b"], np.ndarray) else layer["b"],
+            }
+            if net_name == "oracle_net":
+                oracle_layers.append(entry)
+            else:
+                predictor_layers.append(entry)
+
+        for net_name, layers in (("predictor_net", predictor_layers), ("oracle_net", oracle_layers)):
+            net = getattr(self, net_name, None)
+            if net is None or not layers:
+                continue
+            if len(layers) != len(net.layers):
+                logger.warning(
+                    "Agent %s: skipping %s weight restore — layer count mismatch "
+                    "(file: %d, network: %d)",
+                    self.agent_id, net_name, len(layers), len(net.layers),
+                )
+                continue
+            shape_ok = all(
+                layers[i]["W"].shape == net.layers[i].W.shape
+                and layers[i]["b"].shape == net.layers[i].b.shape
+                for i in range(len(layers))
+            )
+            if not shape_ok:
+                logger.warning(
+                    "Agent %s: skipping %s weight restore — shape mismatch",
+                    self.agent_id, net_name,
+                )
+                continue
+            try:
+                net.set_weights(layers)
+                logger.debug("Agent %s: restored %s weights", self.agent_id, net_name)
+            except (ValueError, AttributeError) as exc:
+                logger.warning(
+                    "Agent %s: could not restore %s weights: %s",
+                    self.agent_id, net_name, exc,
+                )
+
+    # ------------------------------------------------------------------
+    # Subclass contract
+    # ------------------------------------------------------------------
+
+    @property
+    @abstractmethod
+    def subscribed_types(self) -> Set[MessageType]:  # type: ignore[override]
+        ...
+
+    @abstractmethod
+    async def _handle_message(self, message: Message) -> None:
+        ...

mannf/core/agents/belief_state.py

@@ -0,0 +1,202 @@
+# 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.
+
+"""BDI Belief State for NAT agents.
+
+Implements the probabilistic belief revision model described in Chapter 3 of
+the NeuroAgentTest (NAT) thesis.  Beliefs represent fault-likelihood
+estimates per service; they are updated with *bounded* delta rules that
+prevent rapid oscillation (a known failure mode documented in Appendix A.3).
+
+Key design choices (directly from the thesis):
+  * Belief updates are *weighted* by prior confidence.
+  * Maximum per-cycle update magnitude is capped at MAX_DELTA.
+  * Confidence increases monotonically with evidence accumulation.
+  * Entropy thresholds are enforced to prevent premature convergence.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+
+
+# Thesis-defined safeguards (Section 4.5 & Appendix A.1)
+_MAX_DELTA: float = 0.20        # maximum per-cycle belief change
+_MIN_ENTROPY: float = 0.10      # minimum Shannon entropy (exploration quota)
+_MOMENTUM: float = 0.15         # momentum for smoothing belief updates
+_CONFIDENCE_SHAPE: float = 1.0  # controls how fast confidence grows
+
+
+@dataclass
+class BeliefState:
+    """Probabilistic BDI beliefs about service fault likelihood.
+
+    Parameters
+    ----------
+    services:
+        Names of all known services in the system under test.
+    initial_belief:
+        Starting fault-likelihood estimate for all services (0.5 = uncertain).
+    """
+
+    services: List[str]
+    initial_belief: float = 0.5
+
+    # Fault-likelihood per service (0 = definitely safe, 1 = definitely faulty)
+    fault_likelihood: Dict[str, float] = field(default_factory=dict)
+
+    # Confidence in each belief: grows with evidence count
+    confidence: Dict[str, float] = field(default_factory=dict)
+
+    # Update momentum (exponential moving average of deltas per service)
+    _momentum: Dict[str, float] = field(default_factory=dict)
+
+    # Evidence counts per service
+    _counts: Dict[str, int] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for svc in self.services:
+            self.fault_likelihood[svc] = self.initial_belief
+            self.confidence[svc] = 0.0
+            self._momentum[svc] = 0.0
+            self._counts[svc] = 0
+
+    # ------------------------------------------------------------------
+    # Belief revision
+    # ------------------------------------------------------------------
+
+    def update(self, service: str, evidence: float, learning_rate: float = 0.15) -> float:
+        """Update fault-likelihood belief for *service* with new *evidence*.
+
+        Parameters
+        ----------
+        service:
+            Name of the service the evidence pertains to.
+        evidence:
+            Observed fault signal in [0, 1] (1 = fault detected).
+        learning_rate:
+            Base learning step (will be modulated by confidence).
+
+        Returns
+        -------
+        float
+            The updated belief value.
+        """
+        if service not in self.fault_likelihood:
+            # Dynamically register unknown service
+            self.fault_likelihood[service] = self.initial_belief
+            self.confidence[service] = 0.0
+            self._momentum[service] = 0.0
+            self._counts[service] = 0
+
+        prior = self.fault_likelihood[service]
+        conf = self.confidence[service]
+
+        # Scale step by (1 - confidence) so high-confidence beliefs change slowly
+        effective_lr = learning_rate * (1.0 - conf * 0.8)
+
+        # Raw gradient toward evidence
+        raw_delta = effective_lr * (evidence - prior)
+
+        # Apply momentum for smooth updates (mitigates oscillation)
+        self._momentum[service] = (
+            _MOMENTUM * self._momentum[service] + (1.0 - _MOMENTUM) * raw_delta
+        )
+        delta = self._momentum[service]
+
+        # Hard cap (Thesis Section 4.5: belief caps limit rapid oscillation)
+        delta = max(-_MAX_DELTA, min(_MAX_DELTA, delta))
+
+        new_belief = max(0.01, min(0.99, prior + delta))
+        self.fault_likelihood[service] = new_belief
+
+        # Update confidence: grows as √evidence_count, capped at 0.95
+        n = self._counts[service] + 1
+        self._counts[service] = n
+        self.confidence[service] = min(0.95, 1.0 - 1.0 / math.sqrt(n + _CONFIDENCE_SHAPE))
+
+        return new_belief
+
+    # ------------------------------------------------------------------
+    # Prioritisation helpers
+    # ------------------------------------------------------------------
+
+    def prioritise(self) -> List[str]:
+        """Return services sorted by descending fault likelihood.
+
+        Enforces the *exploration quota* from Thesis Section 4.5: services
+        with belief below entropy threshold are always included so the system
+        doesn't over-exploit high-risk areas.
+        """
+        ranked = sorted(
+            self.services, key=lambda s: self.fault_likelihood.get(s, 0.5), reverse=True
+        )
+        return ranked
+
+    def entropy(self) -> float:
+        """Shannon entropy of the fault-likelihood distribution.
+
+        Higher entropy means beliefs are spread evenly (exploratory);
+        lower entropy means the system is focused on specific services.
+        """
+        beliefs = [self.fault_likelihood.get(s, 0.5) for s in self.services]
+        if not beliefs:
+            return 0.0
+        total = sum(beliefs)
+        if total == 0:
+            return 0.0
+        probs = [b / total for b in beliefs]
+        return float(-sum(p * math.log(p + 1e-12) for p in probs))
+
+    def exploration_deficit(self) -> float:
+        """How far entropy is below the minimum threshold (0 = healthy)."""
+        return max(0.0, _MIN_ENTROPY - self.entropy())
+
+    def snapshot(self) -> Dict[str, float]:
+        """Return a copy of the current fault-likelihood beliefs."""
+        return dict(self.fault_likelihood)
+
+    def export_snapshot(
+        self,
+        run_id: str = "",
+        iteration: int = 0,
+        timestamp: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Return a JSON-serialisable snapshot suitable for persistence.
+
+        Parameters
+        ----------
+        run_id:
+            Autonomous run identifier.
+        iteration:
+            Loop iteration number when the snapshot was taken.
+        timestamp:
+            ISO-8601 timestamp string.  When omitted, the current UTC time
+            is used.
+
+        Returns
+        -------
+        dict
+            ``{run_id, iteration, timestamp, beliefs: {page_key: fault_likelihood}}``
+        """
+        import datetime  # noqa: PLC0415
+
+        ts = timestamp or datetime.datetime.now(datetime.timezone.utc).isoformat()
+        return {
+            "run_id": run_id,
+            "iteration": iteration,
+            "timestamp": ts,
+            "beliefs": dict(self.fault_likelihood),
+            "confidence": dict(self.confidence),
+            "momentum": dict(self._momentum),
+        }
+
+    def top_k(self, k: int) -> List[str]:
+        """Return the *k* services with the highest fault likelihood."""
+        return self.prioritise()[:k]