base.py
1"""Shared decision-run lifecycle, independent of policies, tools, SQL and UI.23Concrete runners choose how decisions are produced and how market work is4scheduled. Both stop() and close() terminate work and release owned resources;5pause() retains work. Observation/action and tool APIs stay on their subclasses.6"""78from __future__ import annotations910from abc import ABC, abstractmethod11from typing import Any, Dict, Optional1213from sim_platform.domain.models import ContractError141516class DecisionRunner(ABC):17 """Lifecycle contract for one run's decision method (Human/Rule policy or Agent).1819 Platform creates a runner; the experiment's ResearchController owns it and is the20 only caller of its lifecycle methods. ``background`` is True when the runner21 advances the market on its own threads/children, so poll() only inspects progress.22 """2324 background = False2526 @property27 @abstractmethod28 def run_id(self) -> str:29 """Persistent run identity bound to this decision maker."""3031 @property32 @abstractmethod33 def active(self) -> bool:34 """Whether ready/running/paused work can still continue."""3536 @property37 @abstractmethod38 def closed(self) -> bool:39 """Whether this runner has released its execution resources."""4041 @abstractmethod42 def play(self, speed: Optional[float] = None) -> Any:43 """Start or resume the runner's own scheduling mechanism."""4445 @abstractmethod46 def pause(self) -> Any:47 """Suspend advancement while retaining unfinished work."""4849 @abstractmethod50 def poll(self, *, max_events: int = 1, budget_seconds: Optional[float] = None) -> Any:51 """Service synchronous work or inspect background progress; never double-drive."""5253 @property54 def archive_ready(self) -> bool:55 """Whether the experiment may safely read the market for its archive."""56 return True5758 def detached_view(self) -> Optional[Dict[str, Any]]:59 """Return a published background view, or None for synchronous capture."""60 return None6162 @property63 def policy_controls(self) -> Any:64 raise ContractError('this runner does not provide policy controls')6566 @property67 def tool_controls(self) -> Any:68 raise ContractError('this runner does not provide agent tools')6970 def step(self) -> Any:71 raise ContractError('this runner does not provide single-step playback')7273 @abstractmethod74 def close(self) -> None:75 """Terminate and release owned execution resources; safe to repeat."""7677 def stop(self) -> None:78 self.close()7980 def __enter__(self) -> DecisionRunner:81 return self8283 def __exit__(self, *_: object) -> None:84 self.close()