dyon 0.7.0__py3-none-any.whl

dyon/__init__.py

@@ -0,0 +1,16 @@
+"""Dyon: Domain-agnostic Python framework for digital twin architectures."""
+
+__version__ = "0.6.0"
+
+from dyon.core.base import AbstractDigitalTwin, LayerBase
+from dyon.core.config import TwinConfig, SensorFieldSpec
+from dyon.core.events import EventBus, DomainEvent
+
+__all__ = [
+    "AbstractDigitalTwin",
+    "LayerBase",
+    "TwinConfig",
+    "SensorFieldSpec",
+    "EventBus",
+    "DomainEvent",
+]

dyon/_compat.py

@@ -0,0 +1,66 @@
+"""Compatibility support for the legacy ``dt_forge`` import name.
+
+``dt_forge`` was renamed to ``dyon``. :func:`install_alias` registers a meta-path
+hook so that every ``dt_forge`` / ``dt_forge.*`` import is served by the matching
+``dyon`` module — the *same* module object, so identity, ``isinstance`` and
+module-level singletons stay consistent across both names.
+
+The logic lives here (shipped with ``dyon``) so the ``dt_forge`` shim package is a
+trivial two-line forwarder with nothing to drift out of sync.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import warnings
+from importlib.abc import Loader, MetaPathFinder
+from importlib.machinery import ModuleSpec
+
+_OLD = "dt_forge"
+_NEW = "dyon"
+
+
+class _AliasLoader(Loader):
+    """Loads an old-name module by handing back the real ``dyon`` module object."""
+
+    def __init__(self, target: str) -> None:
+        self._target = target
+
+    def create_module(self, spec: ModuleSpec):
+        module = importlib.import_module(self._target)
+        sys.modules[spec.name] = module
+        return module
+
+    def exec_module(self, module) -> None:  # already initialised as ``dyon.*``
+        pass
+
+
+class _AliasFinder(MetaPathFinder):
+    """Redirects ``dt_forge`` / ``dt_forge.<sub>`` to ``dyon`` / ``dyon.<sub>``."""
+
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname == _OLD or fullname.startswith(_OLD + "."):
+            return ModuleSpec(fullname, _AliasLoader(_NEW + fullname[len(_OLD):]))
+        return None
+
+
+def install_alias(*, warn: bool = True) -> None:
+    """Make ``dt_forge`` resolve to ``dyon``. Idempotent; safe to call repeatedly."""
+    if not any(isinstance(f, _AliasFinder) for f in sys.meta_path):
+        # Insert ahead of the default path finder so submodules alias rather than
+        # re-import under a second name.
+        sys.meta_path.insert(0, _AliasFinder())
+
+    if warn:
+        warnings.warn(
+            "'dt_forge' has been renamed to 'dyon'. Update your imports to 'dyon' "
+            "(e.g. 'import dyon', 'from dyon.core.config import TwinConfig'). The "
+            "'dt_forge' compatibility alias will be removed in a future major release.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+
+    # Serve ``import dt_forge`` itself from the real package, so attribute access
+    # (``dt_forge.AbstractDigitalTwin``) resolves identically to ``dyon``.
+    sys.modules[_OLD] = importlib.import_module(_NEW)

dyon/autonomous/__init__.py

@@ -0,0 +1,19 @@
+from dyon.autonomous.base import AbstractAutonomousController
+from dyon.autonomous.ooda import OODALoop
+from dyon.autonomous.overseer import AutonomousOverseer, OverseerDecision
+from dyon.autonomous.planner import GoalPlanner, Goal
+from dyon.autonomous.gym_env import GenericTwinEnv
+from dyon.autonomous.trainer import PolicyTrainer
+from dyon.autonomous.deployer import PolicyDeployer
+
+__all__ = [
+    "AbstractAutonomousController",
+    "OODALoop",
+    "AutonomousOverseer",
+    "OverseerDecision",
+    "GoalPlanner",
+    "Goal",
+    "GenericTwinEnv",
+    "PolicyTrainer",
+    "PolicyDeployer",
+]

dyon/autonomous/base.py

@@ -0,0 +1,29 @@
+"""Abstract base for autonomous controllers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class AbstractAutonomousController(ABC):
+    """Base class for any autonomous control strategy."""
+
+    @abstractmethod
+    async def observe(self) -> dict:
+        """Collect a comprehensive situation snapshot."""
+        ...
+
+    @abstractmethod
+    async def orient(self, observation: dict) -> dict:
+        """Contextualise the situation against goals."""
+        ...
+
+    @abstractmethod
+    async def decide(self, observation: dict, assessment: dict) -> dict:
+        """Select an action plan."""
+        ...
+
+    @abstractmethod
+    async def act(self, plan: dict) -> None:
+        """Execute the decided plan."""
+        ...

dyon/autonomous/deployer.py

@@ -0,0 +1,91 @@
+"""PolicyDeployer: live RL inference using a trained SB3 policy."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from dyon.data.storage.base import TimeSeriesStore
+    from dyon.network.transport import MQTTTransport
+    from dyon.core.config import TwinConfig
+
+log = logging.getLogger(__name__)
+
+
+class PolicyDeployer:
+    """
+    Loads a trained SB3 policy and applies it in a live twin loop.
+
+    On each step_once() call:
+    1. Reads current observations from InfluxDB
+    2. Runs the policy to get an action
+    3. Publishes the control command via MQTT
+    """
+
+    def __init__(
+        self,
+        policy_path: str | None,
+        config: "TwinConfig",
+        ts_store: "TimeSeriesStore",
+        mqtt_transport: "MQTTTransport",
+        obs_fields: list[str],
+        control_field: str,
+        ctrl_min: float,
+        ctrl_max: float,
+        algorithm: str = "SAC",
+        policy=None,
+    ):
+        from stable_baselines3 import SAC, TD3, PPO, A2C
+
+        self._cfg = config
+        self._ts = ts_store
+        self._mqtt = mqtt_transport
+        self._obs_fields = obs_fields
+        self._control_field = control_field
+        self._ctrl_min = ctrl_min
+        self._ctrl_max = ctrl_max
+
+        if policy is not None:
+            # An already-loaded policy/algorithm (e.g. a BC or imitation policy,
+            # or anything exposing .predict(obs, deterministic=...)).
+            self._policy = policy
+            log.info("PolicyDeployer using preloaded policy (%s)", algorithm)
+        else:
+            # Imitation/BC artifacts are saved in a PPO container, so "BC" loads
+            # through PPO.
+            _algo_map = {"SAC": SAC, "TD3": TD3, "PPO": PPO, "A2C": A2C, "BC": PPO}
+            AlgoClass = _algo_map.get(algorithm.upper(), SAC)
+            self._policy = AlgoClass.load(policy_path)
+            log.info("PolicyDeployer loaded '%s' (%s)", policy_path, algorithm)
+
+    async def _get_observation(self) -> np.ndarray:
+        # A field with no data falls back to its configured nominal value rather
+        # than a hard 0.0 — a 0.0 can sit outside the policy's observation bounds
+        # and misrepresents "no reading" as a genuine zero.
+        latest = await self._ts.aget_latest_fields(self._obs_fields)
+        specs = self._cfg.field_specs
+        obs = []
+        for f in self._obs_fields:
+            v = latest.get(f)
+            if v is None:
+                spec = specs.get(f)
+                v = spec.nominal if spec and spec.nominal is not None else 0.0
+            obs.append(v)
+        return np.array(obs, dtype=np.float32)
+
+    def _scale_action(self, action: np.ndarray) -> float:
+        a = float(np.clip(action[0], -1.0, 1.0))
+        return self._ctrl_min + (a + 1.0) / 2.0 * (self._ctrl_max - self._ctrl_min)
+
+    async def step_once(self) -> float:
+        obs = await self._get_observation()
+        action, _ = self._policy.predict(obs, deterministic=True)
+        ctrl = self._scale_action(action)
+        self._mqtt.publish(
+            self._cfg.topic_control,
+            {self._control_field: round(ctrl, 4)},
+        )
+        return ctrl

dyon/autonomous/gym_env.py

@@ -0,0 +1,124 @@
+"""GenericTwinEnv: Gymnasium environment wrapping any TwinModel."""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable, TYPE_CHECKING
+
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+
+if TYPE_CHECKING:
+    from dyon.simulation.base import TwinModel
+
+log = logging.getLogger(__name__)
+
+
+class GenericTwinEnv(gym.Env):
+    """
+    Gymnasium environment that wraps any TwinModel.
+
+    Configuration:
+        model           — TwinModel instance to use as the environment
+        control_field   — name of the variable the agent adjusts
+        process_variable— name of the variable being regulated
+        target          — desired value for process_variable
+        ctrl_min/max    — valid range for control output
+        obs_fields      — field names forming the observation
+        obs_low/high    — bounds for observation space
+        reward_fn       — optional custom reward function(obs, target) → float
+        max_steps       — episode length
+    """
+
+    metadata = {"render_modes": []}
+
+    def __init__(
+        self,
+        *,
+        model: "TwinModel",
+        control_field: str,
+        process_variable: str,
+        target: float,
+        ctrl_min: float,
+        ctrl_max: float,
+        obs_fields: list[str],
+        obs_low: np.ndarray,
+        obs_high: np.ndarray,
+        reward_fn: Callable | None = None,
+        max_steps: int = 500,
+    ):
+        super().__init__()
+        self.model = model
+        self.control_field = control_field
+        self.process_variable = process_variable
+        self.target = target
+        self.ctrl_min = ctrl_min
+        self.ctrl_max = ctrl_max
+        self.obs_fields = obs_fields
+        self.reward_fn = reward_fn or self._default_reward
+        self.max_steps = max_steps
+        self._step_count = 0
+        self._last_obs: dict[str, float] = {}
+
+        self.observation_space = spaces.Box(
+            obs_low.astype(np.float32),
+            obs_high.astype(np.float32),
+            dtype=np.float32,
+        )
+        self.action_space = spaces.Box(
+            np.array([-1.0], dtype=np.float32),
+            np.array([1.0], dtype=np.float32),
+            shape=(1,),
+            dtype=np.float32,
+        )
+
+    def _default_reward(self, obs: dict, target: float) -> float:
+        # Prefer the simulator-prefixed value but fall back to the bare field.
+        # ``or`` chains would mis-fire when the value is a legitimate 0.0, so
+        # check membership / None explicitly.
+        pv = obs.get(f"sim_{self.process_variable}")
+        if pv is None:
+            pv = obs.get(self.process_variable)
+        if pv is None:
+            pv = 0.0
+        return -abs(pv - target)
+
+    def _scale_action(self, action: np.ndarray) -> float:
+        """Map [-1, 1] → [ctrl_min, ctrl_max]."""
+        a = float(np.clip(action[0], -1.0, 1.0))
+        return self.ctrl_min + (a + 1.0) / 2.0 * (self.ctrl_max - self.ctrl_min)
+
+    def _get_obs(self) -> np.ndarray:
+        return np.array(
+            [self._last_obs.get(f, 0.0) for f in self.obs_fields],
+            dtype=np.float32,
+        )
+
+    def reset(self, *, seed=None, options=None):
+        super().reset(seed=seed)
+        self.model.reset()
+        self._step_count = 0
+        # Prime the first observation from a real model step at the neutral
+        # action (0 → mid-range control), instead of returning an all-zeros
+        # vector: zeros ignore the model's actual initial state and can fall
+        # outside the observation Box bounds when obs_low > 0.
+        neutral_ctrl = self._scale_action(np.array([0.0], dtype=np.float32))
+        self._last_obs = self.model.step(
+            dt=1.0, inputs={self.control_field: neutral_ctrl}
+        )
+        obs = self._get_obs()
+        return obs, {}
+
+    def step(self, action: np.ndarray):
+        ctrl = self._scale_action(action)
+        outputs = self.model.step(dt=1.0, inputs={self.control_field: ctrl})
+        self._last_obs = outputs
+        obs = self._get_obs()
+        reward = self.reward_fn(outputs, self.target)
+        self._step_count += 1
+        terminated = self._step_count >= self.max_steps
+        return obs, reward, terminated, False, {}
+
+    def render(self): ...
+    def close(self): ...

dyon/autonomous/ooda.py

@@ -0,0 +1,253 @@
+"""OODALoop: Observe-Orient-Decide-Act autonomous control layer."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import TYPE_CHECKING
+
+from dyon.autonomous.base import AbstractAutonomousController
+from dyon.core.base import LayerBase
+from dyon.core.events import DomainEvent
+
+if TYPE_CHECKING:
+    from dyon.autonomous.deployer import PolicyDeployer
+    from dyon.autonomous.overseer import AutonomousOverseer
+    from dyon.autonomous.planner import GoalPlanner
+    from dyon.core.config import TwinConfig
+    from dyon.core.events import EventBus
+    from dyon.data.storage.base import CacheStore, DocumentStore, TimeSeriesStore
+    from dyon.intelligent.mas import MultiAgentSystem
+    from dyon.notifications.notifier import HumanNotifier
+    from dyon.reactive.rule_engine import ThresholdRuleEngine
+    from dyon.services.ditto.client import DittoClient
+    from dyon.simulation.base import TwinModel
+
+log = logging.getLogger(__name__)
+
+
+# Maps the assessment/overseer risk vocabulary to the three log-event severity
+# levels the framework uses (DocumentStore.log_event accepts info/warning/critical).
+_RISK_TO_SEVERITY = {
+    "low":      "info",
+    "medium":   "info",
+    "high":     "warning",
+    "critical": "critical",
+}
+
+
+class OODALoop(LayerBase, AbstractAutonomousController):
+    """
+    The OODA loop provides full situational awareness and autonomous control.
+
+    Observe  — gather state from all lower layers
+    Orient   — contextualise using models, history, goals
+    Decide   — select action plan (rule-based, RL policy, goal planner)
+    Act      — execute actions on lower layers or via connectors
+    """
+
+    layer_name = "autonomous"
+
+    def __init__(
+        self,
+        config: "TwinConfig",
+        event_bus: "EventBus",
+        *,
+        ts_store: "TimeSeriesStore",
+        cache: "CacheStore",
+        doc_store: "DocumentStore",
+        ditto_client: "DittoClient",
+        models: dict[str, "TwinModel"],
+        reactive: "ThresholdRuleEngine",
+        mas: "MultiAgentSystem",
+        connectors: list,
+        planner: "GoalPlanner",
+        policy: "PolicyDeployer | None" = None,
+        loop_interval: int = 5,
+        notifier: "HumanNotifier | None" = None,
+        overseer: "AutonomousOverseer | None" = None,
+    ):
+        super().__init__(config, event_bus)
+        self.ts = ts_store
+        self.cache = cache
+        self.doc = doc_store
+        self.ditto = ditto_client
+        self.models = models
+        self.reactive = reactive
+        self.mas = mas
+        self.connectors = connectors
+        self.planner = planner
+        self.policy = policy
+        self.loop_interval = loop_interval
+        self.notifier = notifier
+        # Optional LLM overseer — when set, its strategic decision is merged
+        # into the assessment dict the rule-based planner produces.
+        self.overseer = overseer
+
+    async def observe(self) -> dict:
+        base = {
+            "state": await self.cache.aget_state(),
+            "health": await self.cache.aget_latest_cached("health_score"),
+            "telemetry": await self.ts.aget_latest_fields(self.config.field_names),
+            "recent_events": await self.doc.aget_recent_events(5),
+        }
+        if self.mas:
+            base["mas_findings"] = {
+                a.agent_name: self.mas.get_agent_detail(a.agent_name)
+                for a in self.mas.agents
+            }
+        return base
+
+    async def direct_agent(self, agent_name: str, question: str) -> str:
+        """Send a targeted query to a named MAS agent from the autonomous layer."""
+        if self.mas is None:
+            return "MAS layer not available."
+        return await self.mas.ask_agent(agent_name, question)
+
+    async def orient(self, observation: dict) -> dict:
+        assessment = await self.planner.assess(observation)
+        if self.overseer is not None:
+            try:
+                decision = await self.overseer.run(observation)
+                # The overseer's strategic decision joins the rule-based
+                # assessment under explicit keys so safety constraints in
+                # decide() can still take precedence over it.
+                assessment["overseer_action"] = decision.action
+                assessment["overseer_reasoning"] = decision.reasoning
+                assessment["overseer_risk_level"] = decision.risk_level
+                assessment["overseer_goals_addressed"] = decision.goals_addressed
+                assessment["overseer_agent_queries"] = decision.agent_queries
+                # Audit trail for every overseer decision.
+                try:
+                    await self.doc.alog_event(
+                        "ooda_overseer_decision",
+                        {
+                            "action":           decision.action,
+                            "reasoning":        decision.reasoning,
+                            "risk_level":       decision.risk_level,
+                            "goals_addressed":  decision.goals_addressed,
+                            "agent_queries":    decision.agent_queries,
+                        },
+                        severity="info",
+                    )
+                except Exception as e:
+                    self.log.debug("Overseer audit log failed: %s", e)
+            except Exception as e:
+                self.log.error("Overseer.run failed: %s", e)
+        return assessment
+
+    async def decide(self, observation: dict, assessment: dict) -> dict:
+        # Layer 1 — hard safety constraints from the rule-based planner.
+        # These override the overseer.
+        if assessment.get("requires_human_intervention"):
+            return {
+                "action": "request_human",
+                "reason": assessment.get("reason", "intervention required"),
+            }
+        if assessment.get("requires_shutdown"):
+            return {
+                "action": "shutdown",
+                "reason": assessment.get("reason", "autonomous shutdown"),
+            }
+        if assessment.get("needs_external_data"):
+            return {
+                "action": "query_peer",
+                "target_twin": assessment.get("target_twin", ""),
+                "query": assessment.get("query", {}),
+            }
+
+        # Layer 2 — strategic decision from the overseer (if configured).
+        # The overseer chooses among the actions declared at construction time.
+        overseer_action = assessment.get("overseer_action")
+        if overseer_action and overseer_action != "no_action":
+            return {
+                "action":      overseer_action,
+                "reason":      assessment.get("overseer_reasoning", ""),
+                "risk_level":  assessment.get("overseer_risk_level", "low"),
+                "source":      "overseer",
+            }
+
+        # Layer 3 — RL tactical optimisation when conditions are nominal.
+        if self.policy and assessment.get("risk_level") == "low":
+            return {"action": "rl_control"}
+        return {"action": "maintain_current"}
+
+    async def act(self, plan: dict) -> None:
+        action = plan["action"]
+
+        if action == "request_human":
+            await self.doc.alog_event(
+                "human_intervention_requested", plan, severity="critical"
+            )
+            await self.bus.publish(
+                DomainEvent(
+                    event_type="autonomous.human_requested",
+                    source_layer="autonomous",
+                    source_asset=self.config.asset_id,
+                    payload=plan,
+                    severity="critical",
+                )
+            )
+            self.log.warning("Human intervention requested: %s", plan.get("reason"))
+            if self.notifier:
+                await self.notifier.send(plan.get("reason", "intervention required"), plan)
+
+        elif action == "shutdown":
+            self.reactive.shutdown_asset()  # type: ignore[attr-defined]
+            await self.doc.alog_event("autonomous_shutdown", plan, severity="critical")
+
+        elif action == "query_peer":
+            for conn in self.connectors:
+                if conn.can_reach(plan.get("target_twin", "")):
+                    result = await conn.query(plan["target_twin"], plan.get("query", {}))
+                    await self.doc.alog_event("peer_query", {"result": result}, severity="info")
+                    break
+
+        elif action == "rl_control":
+            if self.policy:
+                await self.policy.step_once()
+
+        elif plan.get("source") == "overseer":
+            # Overseer-defined action: publish an event so domain code can act
+            # on it. Subclasses that know the overseer's action vocabulary
+            # should override act() to drive their own actuators.
+            severity = _RISK_TO_SEVERITY.get(plan.get("risk_level", "low"), "info")
+            await self.bus.publish(
+                DomainEvent(
+                    event_type=f"autonomous.{action}",
+                    source_layer="autonomous",
+                    source_asset=self.config.asset_id,
+                    payload=plan,
+                    severity=severity,
+                )
+            )
+            await self.doc.alog_event(
+                f"autonomous_{action}",
+                plan,
+                severity=severity,
+            )
+
+    async def start(self) -> None:
+        self._running = True
+        self.log.info("OODA autonomous loop started (interval=%ds)", self.loop_interval)
+        while self._running:
+            try:
+                obs = await self.observe()
+                assessment = await self.orient(obs)
+                plan = await self.decide(obs, assessment)
+                await self.act(plan)
+                try:
+                    # Publish a compact summary for the dashboard and monitoring tools.
+                    # Wrapped in try/except so a Redis outage cannot kill the control loop.
+                    await self.cache.aset_latest("ooda_last_cycle", {
+                        "action":     plan.get("action", "unknown"),
+                        "reason":     plan.get("reason", ""),
+                        "risk_level": assessment.get("risk_level", ""),
+                        "ts_s":       int(time.time()),
+                    })
+                except Exception:
+                    pass
+            except Exception as e:
+                self.log.error("OODA loop error: %s", e)
+            await asyncio.sleep(self.loop_interval)