dt-forge 0.3.0__py3-none-any.whl

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/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/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/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/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/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)

dt_forge/autonomous/overseer.py

@@ -0,0 +1,255 @@
+"""AutonomousOverseer: LLM-driven Layer 6 decision agent for the OODA loop."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Callable, Awaitable
+
+if TYPE_CHECKING:
+    from dt_forge.core.config import TwinConfig
+    from dt_forge.intelligent.mas import MultiAgentSystem
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class OverseerDecision:
+    """Structured output from one overseer reasoning cycle."""
+    action: str
+    reasoning: str
+    risk_level: str
+    goals_addressed: list[str] = field(default_factory=list)
+    agent_queries: list[dict] = field(default_factory=list)
+
+
+_SAFE_DEFAULT = OverseerDecision(
+    action="no_action",
+    reasoning="Overseer did not produce a structured decision — defaulting to no_action.",
+    risk_level="low",
+)
+
+
+class AutonomousOverseer:
+    """
+    LangChain tool-calling agent that drives the OODA orient and decide phases.
+
+    On each call to run(), the overseer:
+      1. Receives a formatted observation including all MAS agent findings
+      2. Optionally calls query_mas_agent to interrogate specific agents
+      3. Calls submit_decision to produce a structured OverseerDecision
+
+    The decision is logged verbatim for human audit.  The OODA loop's decide()
+    method then applies hard safety constraints on top — the overseer handles
+    strategy, the constraints handle safety boundaries.
+
+    Parameters
+    ----------
+    config         : TwinConfig
+    llm            : LangChain chat model (ChatOllama, ChatOpenAI, etc.)
+    mas            : The OODA loop's own MultiAgentSystem
+    goals          : Goal names in priority order (used in system prompt)
+    available_actions : Action strings the overseer may choose
+    extra_query_fn : Optional async (agent_name, question) -> str for cross-MAS queries
+    """
+
+    def __init__(
+        self,
+        config: "TwinConfig",
+        llm,
+        mas: "MultiAgentSystem",
+        goals: list[str],
+        available_actions: list[str],
+        extra_query_fn: Callable[[str, str], Awaitable[str]] | None = None,
+    ):
+        from langchain_classic.agents import AgentExecutor, create_tool_calling_agent
+        from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+        from langchain_core.tools import StructuredTool
+
+        self._mas = mas
+        self._available_actions = available_actions
+        self._extra_query_fn = extra_query_fn
+        self._captured: OverseerDecision | None = None
+        self._queries: list[dict] = []
+
+        async def _query_agent(agent_name: str, question: str) -> str:
+            """Query a named MAS agent for deeper analysis on a specific topic.
+
+            agent_name: exact agent name (e.g. 'irrigation_decision', 'soil_moisture_monitor')
+            question: specific analytical question to put to the agent
+            """
+            try:
+                if self._extra_query_fn:
+                    result = await self._extra_query_fn(agent_name, question)
+                else:
+                    result = await self._mas.ask_agent(agent_name, question)
+                self._queries.append({
+                    "agent": agent_name,
+                    "question": question,
+                    "answer": result[:500],
+                })
+                return result
+            except Exception as e:
+                return f"Error querying '{agent_name}': {e}"
+
+        def _submit_decision(
+            action: str,
+            reasoning: str,
+            risk_level: str,
+            goals_addressed: list[str] | None = None,
+        ) -> str:
+            """Submit your final autonomous decision. You MUST call this tool.
+
+            action       : one of the available actions listed in your instructions
+            reasoning    : full explanation — cite specific agent findings and sensor values
+            risk_level   : 'low', 'medium', 'high', or 'critical'
+            goals_addressed : list of goal names this decision serves
+            """
+            self._captured = OverseerDecision(
+                action=action,
+                reasoning=reasoning,
+                risk_level=risk_level,
+                goals_addressed=goals_addressed or [],
+                agent_queries=list(self._queries),
+            )
+            return "Decision recorded."
+
+        tools = [
+            StructuredTool.from_function(
+                coroutine=_query_agent,
+                name="query_mas_agent",
+                description=(
+                    "Query a specific MAS agent by name for deeper analysis. "
+                    "Use when findings are ambiguous or you need more detail before deciding."
+                ),
+            ),
+            StructuredTool.from_function(
+                func=_submit_decision,
+                name="submit_decision",
+                description=(
+                    "Submit your final autonomous decision. "
+                    "MUST be called before finishing your analysis."
+                ),
+            ),
+        ]
+
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", self._system_prompt(config, goals, available_actions)),
+            ("human", "{input}"),
+            MessagesPlaceholder("agent_scratchpad"),
+        ])
+
+        agent = create_tool_calling_agent(llm, tools, prompt)
+        self.executor = AgentExecutor(
+            agent=agent, tools=tools,
+            verbose=False,
+            max_iterations=8,  # cap tool-call rounds to prevent runaway LLM loops
+            return_intermediate_steps=False,
+        )
+
+    @staticmethod
+    def _system_prompt(config, goals: list[str], available_actions: list[str]) -> str:
+        goals_block = "\n".join(f"  {i+1}. {g}" for i, g in enumerate(goals))
+        actions_block = ", ".join(f"'{a}'" for a in available_actions)
+        return (
+            f"You are the Autonomous Overseer of the '{config.asset_name}' digital twin "
+            f"(ID: {config.asset_id}). You are Layer 6 — the highest-level autonomous "
+            f"decision maker in a layered control architecture.\n\n"
+            "LAYER RESPONSIBILITIES:\n"
+            "  Layer 4 – Reactive:   Threshold rules, FSM transitions, PID control. "
+            "Handles routine, deterministic situations automatically. You do NOT duplicate these.\n"
+            "  Layer 5 – Intelligent: MAS agents that diagnose, analyse, and reason. "
+            "They observe and produce findings but CANNOT act on their own.\n"
+            "  Layer 6 – You:        Strategic, goal-driven decisions. You read MAS findings, "
+            "query agents for deeper analysis when needed, and decide what the system should do "
+            "at a level no lower layer can handle alone.\n\n"
+            f"YOUR DECLARED GOALS (priority order):\n{goals_block}\n\n"
+            f"AVAILABLE ACTIONS: {actions_block}\n\n"
+            "YOUR PROCESS EACH CYCLE:\n"
+            "1. Read the MAS agent findings. Agents flagging anomalies deserve attention.\n"
+            "2. If any finding is ambiguous or you need deeper analysis, call query_mas_agent.\n"
+            "3. Assess whether the situation requires strategic intervention or is already "
+            "handled by lower layers.\n"
+            "4. Reason explicitly about your declared goals and which are at risk.\n"
+            "5. Call submit_decision with: action, your full reasoning (cite findings and "
+            "sensor values), risk level, and which goals your decision addresses.\n\n"
+            "CONSTRAINTS:\n"
+            "- Choose 'no_action' when the reactive layer already covers the situation.\n"
+            "- Only escalate to actuating actions (e.g. 'irrigate') when agent findings or "
+            "telemetry justify it beyond what rule-based layers already handle.\n"
+            "- Your reasoning is logged verbatim for human audit — be specific and traceable.\n"
+            "- You MUST call submit_decision before finishing."
+        )
+
+    def _format_observation(self, observation: dict) -> str:
+        lines = ["=== CURRENT SYSTEM STATE ==="]
+
+        for key in ("sdt_state", "pdt_state", "bpdt_state", "fsm_state"):
+            if key in observation:
+                lines.append(f"  {key}: {observation[key]}")
+
+        for key in ("vwc_10cm", "cwsi", "psi_mpa", "yield_penalty",
+                    "depl_rate", "et_rate", "time_since_irr_hr",
+                    "vwc_30cm", "time_to_pwp_hr", "time_to_wilting_hr"):
+            if key in observation:
+                v = observation[key]
+                lines.append(f"  {key}: {v:.4f}" if isinstance(v, float) else f"  {key}: {v}")
+
+        # MAS findings — consolidated from all twins
+        all_findings: dict = observation.get("all_mas_findings") or {}
+        if not all_findings:
+            own = observation.get("mas_findings")
+            if own:
+                all_findings = {"this_twin": own}
+
+        if all_findings:
+            lines.append("\n=== MAS AGENT FINDINGS ===")
+            for twin_label, findings in all_findings.items():
+                if not findings:
+                    continue
+                lines.append(f"\n[{twin_label.upper()} agents]")
+                for agent_name, detail in findings.items():
+                    if not detail:
+                        lines.append(f"  {agent_name}: (no data yet)")
+                        continue
+                    err = detail.get("error")
+                    if err:
+                        lines.append(f"  {agent_name}: ERROR — {err}")
+                        continue
+                    anomaly = detail.get("anomaly", False)
+                    findings_inner = detail.get("findings") or {}
+                    action  = findings_inner.get("action", "monitoring")
+                    summary = findings_inner.get("summary", "")
+                    flag = "⚠ ANOMALY" if anomaly else "OK"
+                    lines.append(f"  {agent_name} [{flag}] action={action}")
+                    if summary:
+                        lines.append(f"    {summary[:350]}")
+
+        recent = observation.get("recent_events", [])
+        if recent:
+            lines.append("\n=== RECENT EVENTS ===")
+            for ev in recent[:5]:
+                sev   = ev.get("severity", "info").upper()
+                etype = ev.get("event_type", "unknown")
+                lines.append(f"  [{sev}] {etype}")
+
+        if self._mas:
+            names = [a.agent_name for a in self._mas.agents]
+            lines.append(f"\nAgents you can query: {', '.join(names)}")
+
+        return "\n".join(lines)
+
+    async def run(self, observation: dict) -> OverseerDecision:
+        """Run one overseer cycle. Returns a structured OverseerDecision."""
+        # Reset per-cycle state so findings from the previous run don't bleed through.
+        # _captured and _queries are written by tool closures (_submit_decision, _query_agent).
+        self._captured = None
+        self._queries = []
+        try:
+            await self.executor.ainvoke({"input": self._format_observation(observation)})
+        except Exception as e:
+            log.error("AutonomousOverseer cycle error: %s", e)
+        if self._captured is None:
+            log.warning("Overseer did not call submit_decision — applying safe default")
+            return _SAFE_DEFAULT
+        return self._captured