dt-forge 0.3.0__tar.gz

dt_forge-0.3.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: dt-forge
+Version: 0.3.0
+Summary: Domain-agnostic Python framework for digital twin architectures
+Requires-Python: >=3.11
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: influxdb-client>=1.40
+Requires-Dist: pymongo>=4.6
+Requires-Dist: motor>=3.3
+Requires-Dist: redis>=5.0
+Requires-Dist: minio>=7.2
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pydantic-settings>=2.1
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: fastapi>=0.109
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: httpx>=0.26
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: scipy>=1.12
+Requires-Dist: numpy>=1.26
+Requires-Dist: simpy>=4.1
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: pyod>=1.1
+Requires-Dist: prophet>=1.1
+Requires-Dist: transitions>=0.9
+Requires-Dist: simple-pid>=2.0
+Requires-Dist: neo4j>=5.17
+Requires-Dist: vaderSentiment>=3.3
+Requires-Dist: langchain>=0.1
+Requires-Dist: langchain-community>=0.0.20
+Requires-Dist: langchain-openai>=0.0.5
+Requires-Dist: stable-baselines3>=2.2
+Requires-Dist: gymnasium>=0.29
+Requires-Dist: prefect>=2.14
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.1
+Requires-Dist: pyserial>=3.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.2; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"

dt_forge-0.3.0/dt_forge/__init__.py

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

dt_forge-0.3.0/dt_forge/autonomous/__init__.py

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

dt_forge-0.3.0/dt_forge/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."""
+        ...

dt_forge-0.3.0/dt_forge/autonomous/deployer.py

@@ -0,0 +1,74 @@
+"""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 dt_forge.autonomous.gym_env import GenericTwinEnv
+    from dt_forge.data.storage.base import TimeSeriesStore
+    from dt_forge.network.transport import MQTTTransport
+    from dt_forge.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,
+        config: "TwinConfig",
+        ts_store: "TimeSeriesStore",
+        mqtt_transport: "MQTTTransport",
+        obs_fields: list[str],
+        control_field: str,
+        ctrl_min: float,
+        ctrl_max: float,
+        algorithm: str = "SAC",
+    ):
+        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
+
+        _algo_map = {"SAC": SAC, "TD3": TD3, "PPO": PPO, "A2C": A2C}
+        AlgoClass = _algo_map.get(algorithm.upper(), SAC)
+        self._policy = AlgoClass.load(policy_path)
+        log.info("PolicyDeployer loaded '%s' (%s)", policy_path, algorithm)
+
+    def _get_observation(self) -> np.ndarray:
+        return np.array(
+            [self._ts.get_latest(f) or 0.0 for f in self._obs_fields],
+            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 = 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

dt_forge-0.3.0/dt_forge/autonomous/gym_env.py

@@ -0,0 +1,109 @@
+"""GenericTwinEnv: Gymnasium environment wrapping any TwinModel."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from dt_forge.simulation.base import TwinModel
+
+log = logging.getLogger(__name__)
+
+
+class GenericTwinEnv:
+    """
+    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,
+    ):
+        import gymnasium as gym
+        from gymnasium import spaces
+
+        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:
+        pv = obs.get(f"sim_{self.process_variable}") or obs.get(self.process_variable) or 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):
+        self.model.reset()
+        self._step_count = 0
+        self._last_obs = {}
+        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): ...

dt_forge-0.3.0/dt_forge/autonomous/ooda.py

@@ -0,0 +1,176 @@
+"""OODALoop: Observe-Orient-Decide-Act autonomous control layer."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import TYPE_CHECKING
+
+from dt_forge.autonomous.base import AbstractAutonomousController
+from dt_forge.core.base import LayerBase
+from dt_forge.core.events import DomainEvent
+
+if TYPE_CHECKING:
+    from dt_forge.autonomous.deployer import PolicyDeployer
+    from dt_forge.autonomous.planner import GoalPlanner
+    from dt_forge.core.config import TwinConfig
+    from dt_forge.core.events import EventBus
+    from dt_forge.data.storage.base import CacheStore, DocumentStore, TimeSeriesStore
+    from dt_forge.intelligent.mas import MultiAgentSystem
+    from dt_forge.notifications.notifier import HumanNotifier
+    from dt_forge.reactive.rule_engine import ThresholdRuleEngine
+    from dt_forge.services.ditto.client import DittoClient
+    from dt_forge.simulation.base import TwinModel
+
+log = logging.getLogger(__name__)
+
+
+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,
+    ):
+        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
+
+    async def observe(self) -> dict:
+        base = {
+            "state": self.cache.get_state(),
+            "health": self.cache.get_latest_cached("health_score"),
+            "telemetry": {
+                f: self.ts.get_latest(f) for f in self.config.field_names
+            },
+            "recent_events": self.doc.get_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:
+        return await self.planner.assess(observation)
+
+    async def decide(self, observation: dict, assessment: dict) -> dict:
+        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", {}),
+            }
+        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":
+            self.doc.log_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]
+            self.doc.log_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", {}))
+                    self.doc.log_event("peer_query", {"result": result}, severity="info")
+                    break
+
+        elif action == "rl_control":
+            if self.policy:
+                await self.policy.step_once()
+
+    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.
+                    self.cache.set_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)