m/market labResearch, with a record.
Source on GitHub ↗

platform.py

1"""Composition root: owns resources; downstream objects implement their functions."""23from __future__ import annotations4from typing import (5    TYPE_CHECKING,6    Any,7    Callable,8    ContextManager,9    Dict,10    List,11    Optional,12    Sequence,13    Tuple,14    Union,15    cast,16)17from .api_types import (18    ArchiveReceipt,19    ExecutionMode,20    ExperimentMethod,21    JsonObject,22    JsonValue,23    PreparedReplayResult,24    ReplayVerification,25    RunDetails,26)27from sim_platform.domain.models import AccountSnapshot, ContractError, Intent28from pathlib import Path29import logging30from threading import RLock31from sim_platform.persistence.sql.database import Database32from sim_platform.persistence.paths import data_directory33from sim_platform.persistence.workspace.temporary import AppWorkspace34from sim_platform.resources import cleanup, cleanup_after_error35from .operations import DatabaseOperations36from .execution_operations import ApplicationOperations37from .resources import PlatformResources3839if TYPE_CHECKING:40    from .experiments.contracts import AgentLaunch41    from sim_platform.sdk import AgentFactory42    from sim_platform.agents.operation_log import AgentOperationLog43    from sim_platform.decisions.agent.runner import AgentDecisionRunner44    from sim_platform.decisions.policy.contracts import Policy45    from sim_platform.experiments.execution.market import LocalMarketExecution46    from sim_platform.decisions.policy.live.runner import LivePolicyDecisionRunner47    from sim_platform.decisions.policy.runner import PolicyDecisionRunner48    from sim_platform.experiments.scheduling.clock import ExperimentClock, SharedExperimentClock49    from sim_platform.experiments.scheduling.host import ExperimentRuntimeHandle50    from sim_platform.experiments.execution.session import ExperimentSession51    from sim_platform.execution.models import ExecutionConfig, ExecutionSnapshot52    from sim_platform.execution.session import ExecutionSession53    from sim_platform.market.playback import MarketPlayback54    from sim_platform.market.prepared.session import PreparedSession55    from sim_platform.research.policy_controller import PolicyResearchController56    from .experiments.contracts import AgentBinding57    from sim_platform.models.credentials import CredentialStore58    from sim_platform.replay.runner import RecoveredRun, ReplaySession59    from sim_platform.research.agent_controller import AgentResearchController60    from sim_platform.research.batch import ResearchBatch61    from sim_platform.research.controller import ResearchController62    from sim_platform.research.datasets import DatasetLibrary63    from sim_platform.research.jobs import BackgroundJob6465    MarketInput = Union[MarketPlayback, PreparedSession]6667from .platform_agents import PlatformAgents68from .platform_base import PathInput69from .platform_credentials import PlatformCredentials70from .platform_records import PlatformRecords717273_log = logging.getLogger(__name__)747576class Platform(PlatformRecords, PlatformAgents, PlatformCredentials):77    """Start here to set up, run and inspect local trading experiments.7879    A Platform connects the account database, historical market data and experiment80    controls. Create one Platform for your app, then use its methods to create accounts,81    prepare experiments and read results. You do not need to construct its internal82    services yourself.8384    For a normal experiment, call open_experiment(). It returns a controller: the object85    you use to play, pause, stop and inspect that experiment. If your screen prepares an86    experiment in several steps, use open_research() instead. Both follow the same setup87    path. Creating a Platform alone does not start an experiment.8889    Platform keeps track of the controllers, workers and other resources it creates.90    Use `with Platform(directory) as app` so they are closed before the database closes.91    Methods that return data, such as snapshot(), return a result for that call; reading92    it again later requires another call.9394    An ID is a string returned by a creation method. Pass it back unchanged. A profile95    groups a user's accounts and saved agents. A maker identifies who makes decisions96    (a human, rule or agent). A run is the saved record of one experiment's activity.9798    Money and prices use integers: 10,000 means USD 1. Quantities are shares. A time named99    *_ns uses nanoseconds on the market session's timeline. Agent tool messages have100    separate rules for counters represented as decimal strings.101102    Examples use app for an open Platform and *_id for previously created IDs. Inputs103    such as source_path and agent_settings must be supplied by the caller. Types describe104    the returned Python values; dictionaries remain ordinary dictionaries. Storage,105    market-library and operating-system errors may also reach the caller.106    """107108    # Set in __init__; declared here because the storage helpers are defined first.109    directory: Path110    _credentials: Optional[CredentialStore]111    _database_instance: Optional[Database]112    _database_lock: RLock113    _resources: PlatformResources114115    @property116    def _database(self) -> Database:117        """Get the database, opening it on first use if initialization was deferred.118119        The lock prevents two callers from creating separate database instances. Platform120        keeps the resulting database and closes it during shutdown.121122        Returns:123            Database: Existing or newly initialized storage; closed platforms cannot initialize124            it.125126        Raises:127            ContractError: If an identity, configuration or lifecycle precondition is invalid.128        """129        with self._database_lock:130            if self._database_instance is None:131                self._resources.check_open()132                self._database_instance = Database(self.directory)133            return self._database_instance134135    def _unit_of_work(self, *, write: bool = False) -> ContextManager[Any]:136        """Start a short database transaction for an internal operation.137138        The caller uses the returned context manager with a with block. write selects139        whether the transaction can change data; leaving the block commits or rolls it back.140141        Args:142            write: Whether the internal operation needs a write transaction.143144        Returns:145            ContextManager[Any]: Commits/rolls back at context exit; never retain the ORM146            Session.147148        Raises:149            ContractError: If an identity, configuration or lifecycle precondition is invalid.150        """151        return self._database.unit_of_work(write=write)152153    def __init__(154        self,155        directory: Optional[PathInput] = None,156        *,157        database: bool = True,158        python_manager: Optional[PathInput] = None,159        agent_sdk_wheel: Optional[PathInput] = None,160    ) -> None:161        """Open the local storage and services that your app will use.162163        Call this once before creating accounts or experiments. directory chooses where saved164        data lives. The new Platform is ready to accept calls, but no market or experiment165        has started. A temporary workspace is also created for work files.166167        With database=True, the SQLite database opens now. With database=False, it opens on168        the first database operation; saved data is still enabled. Use a with block to close169        experiments and workers before their storage is closed.170171        Args:172            directory: Storage directory; None selects the per-OS-user default. Explicit paths173                must be absolute.174            database: Open SQLite immediately when True; otherwise initialize on first database175                use.176            python_manager: Trusted uv executable bundled with the App. None uses uv from PATH177                for repository use; never resolved from Agent source.178            agent_sdk_wheel: Optional trusted SDK wheel bundled by the App. Repository use179                builds a wheel from the explicit client-only inventory when omitted.180181        Returns:182            None. The instance starts open, with no research controller or run created.183184        Raises:185            ContractError: If directory is not absolute.186            OSError: If storage cannot be opened; database initialization errors propagate.187188        Example:189            from tempfile import TemporaryDirectory190            with TemporaryDirectory() as folder:191                with Platform(folder) as app:192                    profile_id = app.create_profile('Research')193        """194        self.directory = Path(directory).expanduser() if directory is not None else data_directory()195        if not self.directory.is_absolute():196            raise ContractError('data directory must be absolute')197        self._credentials = None198        self._database_instance = None199        self._database_lock = RLock()200        self._workspace = AppWorkspace()201        self._resources = PlatformResources()202        from sim_platform.execution.coordinator import ExecutionCoordinator203        from sim_platform.persistence.workspace.ownership import AccountLease204        from .replay_manifest import capture_source205        from sim_platform.persistence.export_files import atomic_write206        from sim_platform.persistence.datasets.files import DatasetFiles207208        self._export_writer = atomic_write209        self._dataset_files = DatasetFiles(self.directory)210        self._db_operations = DatabaseOperations(self._unit_of_work)211        execution = ExecutionCoordinator(212            self._db_operations,213            self._resources,214            source_identity=capture_source,215            lease_factory=lambda account: AccountLease(self.directory, account),216            lineage=self._record_lineage,217        )218        self._operations = ApplicationOperations(self._db_operations, execution)219        from sim_platform.persistence.lineage import LineageFiles220        from .lineage import RunLineage221222        self._lineage = RunLineage(223            LineageFiles(self.directory),224            run=self._operations.run,225            events=self._operations.run_events,226            decisions=self._operations.decision_records,227            agent_log=self._operations.agent_log_archive,228        )229        from sim_platform.persistence.agents.projects import ProjectFiles230        from sim_platform.persistence.agents.environments import EnvironmentFiles231        from .agents.projects import AgentProjects232233        self._agent_project_files = ProjectFiles(self.directory)234        self._agent_projects = AgentProjects(self._operations, self._agent_project_files)235        from sim_platform.agents.environments.installer import environment_python236237        self._agent_environment_files = EnvironmentFiles(238            self.directory, python_path=environment_python239        )240        from sim_platform.persistence.agents.sdk import SDKFiles241242        self._agent_sdk = SDKFiles(self.directory, agent_sdk_wheel)243        from sim_platform.persistence.agents.runtimes import RuntimeFiles244        from sim_platform.agents.runtimes.provider import UvPythonProvider245        from sim_platform.agents.runtimes.manager import PythonRuntimes246247        self._python_runtimes = PythonRuntimes(248            RuntimeFiles(self.directory), UvPythonProvider(python_manager)249        )250        from .agents.environments import AgentEnvironments251252        self._agent_environments = AgentEnvironments(253            self._agent_projects,254            self._agent_environment_files,255            self._python_runtimes,256            self._agent_sdk,257        )258        if database:259            try:260                self._database_instance = Database(self.directory)261            except Exception as exc:262                cleanup_after_error(exc, self._workspace.close)263                raise264265    @property266    def closed(self) -> bool:267        """Check whether Platform shutdown has started.268269        Use this when deciding whether the app can still create resources. True means new270        resources are no longer accepted. It does not guarantee that every worker has exited:271        if close() raised an error, fix that problem and call close() again.272273        Returns:274            bool: False initially; True once close() begins, including failed cleanup.275276        Example:277            is_closed = app.closed278        """279        return self._resources.closed280281    def _new_market(282        self, symbol: str = 'AAPL', *, depth: int = 5, library: Optional[PathInput] = None283    ) -> MarketPlayback:284        """Build a market playback object without adding it to Platform cleanup yet.285286        The object has temporary history storage but no loaded source. Its caller must287        either register it for cleanup or attach it to a parent that will close it.288289        Args:290            symbol: Stock symbol, such as AAPL. Trading experiments currently use one291                symbol per run; standalone playback selects the book for this symbol.292            depth: Retained/displayed book levels, from 1 to 100.293            library: Path to the compiled market-data library. Usually omit this to use294                the configured or bundled library.295296        Returns:297            MarketPlayback: Unloaded child; caller must register it or close it on assembly298            failure.299300        Raises:301            ContractError: If an identity, configuration or lifecycle precondition is invalid.302        """303        self._resources.check_open()304        from sim_platform.market import MarketSession305        from sim_platform.market.playback import MarketPlayback306        from sim_platform.market.history import MarketHistory307308        engine = MarketSession(symbol, depth=depth, library=library)309        try:310            files = self._workspace.market_cache()311        except Exception as exc:312            cleanup_after_error(exc, engine.close)313            raise314        try:315            return MarketPlayback(engine, MarketHistory(files))316        except Exception as exc:317            cleanup_after_error(exc, engine.close, files.close)318            raise319320    def _new_research_market(321        self,322        symbol: str = 'AAPL',323        *,324        depth: int = 5,325        library: Optional[PathInput] = None,326        bar_spread: Optional[int] = None,327        bar_origin: Optional[str] = None,328    ) -> PreparedSession:329        """Create the market reader used while preparing a research experiment.330331        It uses the local dataset inventory to find or build prepared historical data.332        The caller attaches the reader to its controller and takes responsibility for closing it.333334        Args:335            symbol: Stock symbol, such as AAPL. Trading experiments currently use one336                symbol per run; standalone playback selects the book for this symbol.337            depth: Retained/displayed book levels, from 1 to 100.338            library: Path to the compiled market-data library. Usually omit this to use339                the configured or bundled library.340            bar_spread: A price-bar recording's synthetic spread in integer money; None341                keeps the default of two cents.342            bar_origin: A price-bar recording's market day 0 ('YYYY-MM-DD'), when it343                shares a timeline with recordings that start earlier.344345        Returns:346            PreparedSession: Unloaded child; no import job starts until load().347348        Raises:349            ContractError: If an identity, configuration or lifecycle precondition is invalid.350        """351        from sim_platform.market.prepared.session import PreparedSession352        from sim_platform.persistence.prepared.store import PreparedStore353354        self._resources.check_open()355        return PreparedSession(356            PreparedStore(self.directory),357            symbol,358            depth=depth,359            library=library,360            bar_spread=bar_spread,361            bar_origin=bar_origin,362        )363364    def open_market(365        self, symbol: str = 'AAPL', *, depth: int = 5, library: Optional[PathInput] = None366    ) -> MarketPlayback:367        """Create a market reader that you can load and advance yourself.368369        Use this to inspect or replay a market file without setting up a trading experiment.370        The returned MarketPlayback starts without a file. Call load() to select data, then371        step() or play() to move through it.372373        Platform closes this object and its temporary history files when Platform closes.374        You can close it earlier. For trading experiments, use open_experiment(), which375        prepares its own market data and connects it to the account and decision runner.376377        Args:378            symbol: Stock symbol, such as AAPL. Trading experiments currently use one379                symbol per run; standalone playback selects the book for this symbol.380            depth: Retained/displayed book levels, from 1 to 100.381            library: Path to the compiled market-data library. Usually omit this to use382                the configured or bundled library.383384        Returns:385            MarketPlayback: An open, unloaded source; no account or execution run is created.386387        Raises:388            ContractError: If the platform is closed.389            MarketError: If symbol/depth is invalid.390            OSError: If the native library cannot be loaded.391            RuntimeError: If a native engine cannot be allocated.392393        Example:394            market = app.open_market('AAPL', depth=5)395            market.load(source_path)396            event = market.step()397            market.close()398        """399        market = self._new_market(symbol, depth=depth, library=library)400        market.on_close(lambda: self._resources.remove(market))401        return self._resources.add(market)402403    def open_jobs(self) -> BackgroundJob:404        """Create a worker for running one slow task away from your calling thread.405406        This is useful when a screen needs to stay responsive during preparation. Creating407        the worker does not start a task. Call start(operation, **arguments), then check its408        progress and collect the result with take_result(). The operation receives a409        cancellation token and must check it if it needs to support cancellation.410411        Platform will close the worker. You can also close it yourself, but close() waits412        for the task to finish or cooperate with cancellation.413414        Returns:415            BackgroundJob: No task submitted; active is False.416417        Raises:418            ContractError: If an identity, configuration or lifecycle precondition is invalid.419420        Example:421            jobs = app.open_jobs()422            jobs.start(operation, source=source_path)423            # Poll jobs.active / take_result() from your own event loop.424            jobs.close()425        """426        self._resources.check_open()427        from sim_platform.research.jobs import BackgroundJob428429        job = BackgroundJob()430        job.on_close(lambda: self._resources.remove(job))431        return self._resources.add(job, shutdown_first=True)432433    def _new_execution(434        self, profile: str, run_id: str, maker: str, market: MarketInput435    ) -> ExecutionSession:436        """Connect a run, account and market to one order-execution session.437438        This internal factory shares Platform's account-ownership checks, so two executors439        cannot write the same account at once. It does not register the session as a root440        resource: the caller must close it or give that responsibility to its runner.441442        Args:443            profile: Profile ID selecting whose saved data and account to use.444            run_id: Existing run ID owned by the selected profile.445            maker: Maker ID with current command authority for the run.446            market: Loaded market borrowed from the caller; it must match the run/source prefix.447448        Returns:449            ExecutionSession: Open account writer; caller owns close, market is borrowed.450451        Raises:452            ContractError: If an identity, configuration or lifecycle precondition is invalid.453        """454        self._resources.check_open()455        from sim_platform.execution import ExecutionSession456457        return ExecutionSession(458            self._operations, profile, run_id, maker, market, ownership=self._resources459        )460461    def _new_runner(462        self, profile: str, run_id: str, maker: str, market: MarketInput, policy: Policy463    ) -> PolicyDecisionRunner:464        """Connect a policy to a market and its order-execution session.465466        This internal factory builds the synchronous runner used for controlled decisions.467        The runner shares the platform's financial command path. Its parent must close the468        runner, while the market remains borrowed from the caller.469470        Args:471            profile: Profile ID selecting whose saved data and account to use.472            run_id: Existing run ID owned by the selected profile.473            maker: Maker ID with current command authority for the run.474            market: Loaded market borrowed from the caller; it must match the run/source prefix.475            policy: Strategy object implementing decisions.contracts.Policy. For an476                existing run, its identity and settings must match the saved policy.477478        Returns:479            PolicyDecisionRunner: Bound child; caller owns cleanup and borrowed market lifetime.480481        Raises:482            ContractError: If an identity, configuration or lifecycle precondition is invalid.483        """484        self._resources.check_open()485        from sim_platform.decisions import PolicyDecisionRunner486        from sim_platform.experiments.execution.market import ExecutionCommands487488        return PolicyDecisionRunner(489            self._operations,490            profile,491            run_id,492            maker,493            market,494            policy,495            execution_factory=self._new_execution,496            commands=ExecutionCommands(self._operations.commit_decision, profile, run_id),497        )498499    def _new_live_policy_runner(500        self, profile: str, run_id: str, maker: str, market: MarketInput, policy: Policy501    ) -> LivePolicyDecisionRunner:502        """Build the policy runner used when an experiment runs in the background.503504        It connects policy decisions to the background execution session and its output505        recording. The controller receives a ready runner and starts it later with Play.506        The parent takes responsibility for closing it.507508        Args:509            profile: Profile ID selecting whose saved data and account to use.510            run_id: Existing run ID owned by the selected profile.511            maker: Maker ID with current command authority for the run.512            market: Loaded market borrowed from the caller; it must match the run/source prefix.513            policy: Strategy object implementing decisions.contracts.Policy. For an514                existing run, its identity and settings must match the saved policy.515516        Returns:517            LivePolicyDecisionRunner: Ready child; no Play until the Controller requests it.518519        Raises:520            ContractError: If an identity, configuration or lifecycle precondition is invalid.521        """522        from .experiments.factory import assemble_live_policy523524        return assemble_live_policy(525            self._new_runner,526            self.directory,527            profile,528            run_id,529            maker,530            # Live experiments always run on a prepared source.531            cast('PreparedSession', market),532            policy,533            pipeline_factory=self._compose_pipeline,534        )535536    def _new_experiment_runtime(537        self,538        configuration: JsonObject,539        *,540        clock: Optional[SharedExperimentClock] = None,541        on_notice: Optional[Callable[[str, JsonObject], None]] = None,542        on_failure: Optional[Callable[[Exception], None]] = None,543        prepared_artifact: Optional[PathInput] = None,544        prepared_news: Sequence[JsonObject] = (),545    ) -> ExperimentRuntimeHandle:546        """Start the separate process that schedules Agent work and model attempts.547548        Use this while assembling an Agent runner. Check that Platform is open, then549        pass the validated run settings and trusted market source to Runtime assembly.550        This call waits for child initialization; it does not start the experiment clock.551552        The returned handle is not registered as a Platform root. The caller must give553        it to the runner or close it if the remaining assembly fails. Model requests554        and financial execution remain owned by their respective components.555556        Args:557            configuration: Complete Agent run configuration, containing references rather558                than credentials. Session start/end values are nanoseconds encoded as strings.559            clock: Shared experiment clock, or None to let Runtime create its default clock.560            on_notice: Optional nonblocking callback receiving an event name and detached561                details from Runtime.562            on_failure: Optional nonblocking callback receiving a Runtime transport or563                child-process failure.564            prepared_artifact: Trusted immutable market directory. Required for assembly;565                its path is supplied to Runtime, never to the Agent program.566            prepared_news: Publication records merged into Runtime's market observation567                index. An empty sequence adds no publications.568569        Returns:570            ExperimentRuntimeHandle: Initialized scheduling child and transport. The caller571                owns close until ownership transfers to the assembled runner.572573        Raises:574            ContractError: If Platform is closed, prepared_artifact is missing, the clock575                or capacity is unsupported, or the child does not become ready.576            AgentConfigurationError: If the supplied run configuration is invalid.577            RuntimeError: If a Runtime transport thread cannot start.578            OSError: If operating-system resources for the child cannot be created.579        """580        from .experiments.runtime import assemble_runtime581582        self._resources.check_open()583        return assemble_runtime(584            configuration,585            clock=clock,586            on_notice=on_notice,587            on_failure=on_failure,588            prepared_artifact=prepared_artifact,589            prepared_news=prepared_news,590        )591592    def run(self, profile_id: str, run_id: str, *, include_records: bool = True) -> RunDetails:593        """Read the saved record of one experiment run.594595        Use this to find its account, decision-maker, configuration and saved status. It596        returns data, not an object that controls the experiment. Reading it does not ask597        the strategy to make a decision or move the market forward.598599        The database status 'running' means the run has not ended. It also covers the time600        before Play and while paused. Use the experiment controller to check playback state.601        Set include_records=False when you do not need the full decision history; the result602        may then come from the committed account data already held in memory.603604        Args:605            profile_id: Profile ID returned by create_profile(); selects whose data to access.606            run_id: Existing run ID owned by the selected profile.607            include_records: Include the full policy decision record journal when True.608609        Returns:610            RunDetails: A dictionary describing this run, including status, time_ns, config, initial_snapshot,611            policy_state and decision_maker.612613        Raises:614            ContractError: If an identity, configuration or lifecycle precondition is invalid.615616        Example:617            details = app.run(profile_id, run_id, include_records=False)618            status = details['status']619        """620        return self._operations.run(profile_id, run_id, include_records=include_records)621622    def execution_session(623        self, profile_id: str, run_id: str, maker_id: str, market: MarketInput624    ) -> ExecutionSession:625        """Connect an existing execution run to the market it will trade against.626627        This is for callers assembling an experiment themselves. First create_execution_run()628        saves the run; this method gives it an ExecutionSession that processes market events629        and order operations for that run. Setup checks the run, its account and market630        position, and prevents another executor from changing the same account at once.631632        You keep responsibility for the market passed in. Close the session before closing633        that market; Platform also tracks and closes the session. Runs configured with a634        policy use decision_runner() instead. Most callers should use open_experiment() to635        have these parts connected for them.636637        Args:638            profile_id: Profile ID returned by create_profile(); selects whose data to access.639            run_id: Existing run ID owned by the selected profile.640            maker_id: Maker ID with current command authority for the run.641            market: Loaded market borrowed from the caller; it must match the run/source prefix.642643        Returns:644            ExecutionSession: Ready to process this run, with its account and orders loaded645            into memory. Market playback has not started.646647        Raises:648            ContractError: If an identity, configuration or lifecycle precondition is invalid.649650        Example:651            session = app.execution_session(profile_id, run_id, maker_id, market)652            event = session.step()653            session.close()654        """655        if 'decision' in self.run(profile_id, run_id, include_records=False)['config']:656            raise ContractError('bind decision runs through DecisionRunner')657        owner = self._new_execution(profile_id, run_id, maker_id, market)658        owner.on_close(lambda: self._resources.remove(owner))659        return self._resources.add(owner)660661    def archive_agent_log(self, profile_id: str, run_id: str, path: PathInput) -> ArchiveReceipt:662        """Save a finished agent's local JSON activity log in the run's database archive.663664        Use this after the run has ended and its log has been sealed, meaning no more records665        can be added. The file is read and checked before the database write. It must belong666        to the requested profile, experiment and run.667668        Saving the same content again is allowed; replacing it with different content is669        rejected. The original JSON file stays on disk. This does not execute its tool calls.670671        Args:672            profile_id: Profile ID returned by create_profile(); selects whose data to access.673            run_id: Existing run ID owned by the selected profile.674            path: Absolute path to a sealed JSON operation log.675676        Returns:677            ArchiveReceipt: run_id and record_count; no new run or trade is created.678679        Raises:680            ContractError: If the log is incomplete, mismatched, conflicting or the run is active.681            OSError: If the log cannot be read.682683        Example:684            receipt = app.archive_agent_log(profile_id, run_id, log_path)685            count = receipt['record_count']686        """687        from sim_platform.agents.operation_log import validate_archive688        from sim_platform.persistence.agent_log_files import read_agent_log689690        archive = validate_archive(read_agent_log(path))691        receipt = self._operations.archive_agent_log(profile_id, run_id, archive)692        try:693            self._lineage.record_agent(profile_id, run_id)694        except Exception:695            _log.warning('Could not record Agent lineage of run %s', run_id, exc_info=True)696        return receipt697698    def _compose_pipeline(699        self,700        driver: LocalMarketExecution,701        market: PreparedSession,702        *,703        end_ns: int,704        sink: Callable[[JsonObject], None],705        operation: Callable[[Any, Dict[str, str]], Any],706        lag_limit_ns: int,707        clock: Optional[Union[ExperimentClock, SharedExperimentClock]] = None,708        start_ns: Optional[int] = None,709        capacity: int = 64,710        lag_window_ns: int = 0,711    ) -> ExperimentSession:712        """Connect a prepared market, clock and financial commands for background execution.713714        Use this while assembling an Agent or Live policy runner. Pipeline assembly715        captures the initial account and execution configuration for recorded Replay,716        and binds the shared event reader used to collect terminal financial evidence.717718        The output stage is created synchronously. The financial execution worker starts719        only when the returned Session is started. The caller must attach the Session to720        its runner or close it on assembly failure; driver and market remain borrowed.721722        Args:723            driver: Owner-only financial execution capability borrowing the existing724                execution session and market cursor.725            market: Loaded PreparedSession matching the run and its source prefix.726            end_ns: Exclusive end in session nanoseconds, clipped to the source coverage.727            sink: Output-stage callback receiving ordered, detached JSON records.728            operation: Trusted short handler receiving a command and its ordered position729                on the sole financial owner.730            lag_limit_ns: Financial processing delay threshold, in nanoseconds.731            clock: Experiment clock, or None to create one at the selected start point.732            start_ns: Start in session nanoseconds, or None to use market.origin_ns.733            capacity: Maximum pending/result slots; defaults to 64. Exhaustion is rejected734                rather than creating an unbounded queue.735            lag_window_ns: Allowed continuous threshold-exceedance duration, in nanoseconds;736                defaults to zero.737738        Returns:739            ExperimentSession: Ready background lifecycle with Replay inputs and terminal740                evidence bound. The financial worker has not started.741742        Raises:743            ContractError: If market is not prepared or the selected interval exceeds744                the prepared source coverage.745            OSError: If required operating-system resources cannot be created.746            RuntimeError: If the output stage cannot start.747        """748        from .experiments.pipeline import assemble_pipeline749750        return assemble_pipeline(751            driver,752            market,753            run_events=self._operations.run_events,754            end_ns=end_ns,755            sink=sink,756            operation=operation,757            lag_limit_ns=lag_limit_ns,758            clock=clock,759            start_ns=start_ns,760            capacity=capacity,761            lag_window_ns=lag_window_ns,762        )763764    def _new_agent_log(765        self, profile_id: str, experiment_id: str, run_id: str, path: PathInput766    ) -> AgentOperationLog:767        """Create the local activity recorder for an agent run being assembled.768769        First check that the saved run belongs to the requested agent experiment. Then open770        the JSON log at its chosen path. The caller must attach the recorder to the runner771        or close it if the remaining setup fails.772773        Args:774            profile_id: Profile ID returned by create_profile(); selects whose data to access.775            experiment_id: Saved Agent experiment draft ID owned by the profile.776            run_id: Existing run ID owned by the selected profile.777            path: Absolute local file path; see lifecycle requirements below.778779        Returns:780            AgentOperationLog: Open unsealed file; caller must close it on rollback.781782        Raises:783            ContractError: If an identity, configuration or lifecycle precondition is invalid.784        """785        from sim_platform.agents.operation_log import AgentOperationLog786        from sim_platform.persistence.agent_log_files import AgentLogFile787788        self._resources.check_open()789        header = self._operations.agent_log_header(profile_id, experiment_id, run_id)790        adapter = AgentLogFile(path)791        try:792            recorder = AgentOperationLog(adapter, header)793        except Exception as exc:794            cleanup_after_error(exc, adapter.close)795            raise796        return recorder797798    def create_agent_log(799        self, profile_id: str, experiment_id: str, run_id: str, path: PathInput800    ) -> AgentOperationLog:801        """Create a local JSON file for recording an agent run's activity.802803        This is a manual setup API. The run must already exist and be connected to its agent804        experiment. The path must be absolute and unused. Normal experiment setup creates805        its own recorder, so most callers do not need this method.806807        The returned recorder writes to a file as the run proceeds. Platform closes it during808        shutdown, but closing alone does not mark the log complete or save it to the database.809        Seal the completed log before calling archive_agent_log().810811        Args:812            profile_id: Profile ID returned by create_profile(); selects whose data to access.813            experiment_id: Saved Agent experiment draft ID owned by the profile.814            run_id: Existing run ID owned by the selected profile.815            path: Absolute path for a new file; existing files are never overwritten.816817        Returns:818            AgentOperationLog: Open recorder with a header written; the log is not sealed.819820        Raises:821            ContractError: If bindings or path are invalid.822            OSError: If the file exists or cannot be created.823824        Example:825            recorder = app.create_agent_log(profile_id, experiment_id, run_id, new_log_path)826            # Record completed operations and finish with the actual terminal status.827            recorder.close()828        """829        recorder = self._new_agent_log(profile_id, experiment_id, run_id, path)830        recorder.on_close(lambda: self._resources.remove(recorder))831        return self._resources.add(recorder)832833    def _cancel_failed_agent_start(self, profile: str, run: str) -> None:834        """Finish cleanup when an agent cannot be assembled after its run was saved.835836        First try to stop a run that has not acquired an executor. If that is no longer837        possible, use the normal execution recovery path. This prevents setup failure from leaving an active run838        that blocks later experiments on the account.839840        Args:841            profile: Profile ID selecting whose saved data and account to use.842            run: Existing owned run ID.843844        Returns:845            None. An active unbound run is stopped, or the financial recovery finish path is846            used.847848        Raises:849            ContractError: If an identity, configuration or lifecycle precondition is invalid.850        """851        if self._operations.run(profile, run, include_records=False)['status'] == 'running':852            if not self._operations.cancel_unbound_agent_run(profile, run):853                self._operations.abort_execution_run(profile, run)854855    def _agent_project_launch(self, profile: str, definition: JsonObject) -> AgentLaunch:856        """Resolve a saved Agent revision and its ready environment for process launch.857858        Use this before constructing the Agent process host. Check ownership and the859        saved project reference, find the compatible prepared environment, then copy the860        saved source into a temporary workspace. This performs local file work synchronously;861        it does not install dependencies or execute Agent code.862863        The caller owns the returned workspace until it transfers the launch to the process864        host. If host assembly cannot take ownership, the caller must close the workspace.865866        Args:867            profile: Profile ID owning the saved Agent revision and source snapshot.868            definition: Validated saved Agent definition containing agent_id, revision869                and package.project_ref. The exact revision is selected for launch.870871        Returns:872            AgentLaunch: Executable and project-directory paths, plus the owned temporary873                source workspace. Pass this launch to the process host during assembly.874875        Raises:876            ContractError: If Platform is closed, ownership or the project reference is877                invalid, or no compatible environment is ready. Prepare the environment878                before retrying launch.879            OSError: If saved source, environment files or the temporary workspace cannot880                be read or created.881        """882        self._resources.check_open()883        return self._agent_environments.launch(profile, definition, self._workspace)884885    def _assemble_agent_runner(886        self,887        profile: str,888        binding: JsonObject,889        market: PreparedSession,890        log_path: Optional[PathInput],891        clock: Optional[SharedExperimentClock] = None,892        *,893        execution_mode: ExecutionMode,894        agent_factory: Optional[AgentFactory] = None,895    ) -> AgentDecisionRunner:896        """Give the agent assembly code the Platform factories it needs.897898        The assembly code connects execution, scheduling, agent tools and JSON recording899        into one AgentDecisionRunner. Passing these factories keeps it on the same account,900        command and cleanup paths as the rest of Platform.901902        Args:903            agent_factory: Optional trusted, spawn-picklable create_agent(context) callable.904                Advanced Python composition hook. Normal callers omit it: configured Agents905                use the template; imported Agents load their saved source and ready environment.906            profile: Profile ID selecting whose saved data and account to use.907            binding: Detached run/maker/experiment/configuration binding returned by the run908                service.909            market: Loaded market borrowed from the caller; it must match the run/source prefix.910            log_path: Absolute path for a new JSON activity log. None chooses the default911                local path for this run.912            clock: Optional trusted shared experiment clock for test/advanced composition;913                normal callers omit it.914            execution_mode: Required playback mode: controlled for caller-driven policy915                execution, live for background execution. Agent currently uses916                background 1x in either mode.917918        Returns:919            AgentDecisionRunner: Ready owned children; registration remains the caller's920            responsibility.921922        Raises:923            ContractError: If an identity, configuration or lifecycle precondition is invalid.924        """925        from .experiments.agent import assemble_agent_runner926        from .experiments.contracts import AgentAssemblyServices927928        return assemble_agent_runner(929            profile,930            cast('AgentBinding', binding),931            market,932            log_path,933            clock,934            services=AgentAssemblyServices(935                runtime_factory=self._new_experiment_runtime,936                execution_factory=self._new_execution,937                compose_pipeline=self._compose_pipeline,938                directory=self.directory,939                create_log=self._new_agent_log,940                archive_log=self.archive_agent_log,941                commit_decision=self._operations.commit_decision,942                failed_start=self._cancel_failed_agent_start,943                resolve_project=self._agent_project_launch,944                presentation_operations=self._operations,945            ),946            agent_factory=agent_factory,947        )948949    def _validate_agent_market(self, market: PreparedSession, source: JsonObject) -> JsonObject:950        """Check that the supplied market is at the agent experiment's intended start.951952        The market must be ready or paused. Its symbol, event sequence and time must match953        the supplied source description, and all events through the chosen start must have954        been processed. This also prepares the market history used by agent reads and955        returns a separate copy of the source description.956957        Args:958            market: Loaded market borrowed from the caller; it must match the run/source prefix.959            source: Detached source identity/start_origin metadata supplied by the trusted960                caller.961962        Returns:963            JsonObject: Detached source metadata; the borrowed market's Agent history capability964            is prepared.965966        Raises:967            ContractError: If an identity, configuration or lifecycle precondition is invalid.968        """969        from sim_platform.domain.json_values import copy_json970971        source = copy_json(source)972        origin = dict(sequence=market.snapshot.sequence, time_ns=market.time_ns)973        if (974            market.status not in ('ready', 'paused')975            or not isinstance(source, dict)976            or source.get('start_origin') != origin977            or source.get('symbol') not in getattr(market, 'universe', (market.snapshot.symbol,))978            or not isinstance(source.get('source_manifest_ref'), str)979        ):980            raise ContractError('supply a ready prepared market with matching source metadata')981        start = source.get('experiment_start_ns', market.time_ns)982        if (983            type(start) is not int984            or start < market.time_ns985            or (market.next_event_time_ns is not None and market.next_event_time_ns <= start)986        ):987            raise ContractError('market prefix is not fully prepared through experiment start')988        market.prepare_agent_history()989        return source990991    def _new_agent_run(992        self,993        profile: str,994        experiment_id: str,995        market: PreparedSession,996        *,997        source: JsonObject,998        log_path: Optional[PathInput],999        clock: Optional[SharedExperimentClock] = None,1000        execution_mode: ExecutionMode,1001        agent_factory: Optional[AgentFactory] = None,1002    ) -> AgentDecisionRunner:1003        """Create an actual run from a saved agent experiment draft.10041005        After checking the market and execution mode, save the run and assemble its agent1006        runner. The draft is saved configuration; the new run records this execution.1007        The parent controller must close the returned runner.10081009        Args:1010            agent_factory: Optional trusted, spawn-picklable create_agent(context) callable.1011                Advanced Python composition hook. Normal callers omit it: configured Agents1012                use the template; imported Agents load their saved source and ready environment.1013            profile: Profile ID selecting whose saved data and account to use.1014            experiment_id: Saved Agent experiment draft ID owned by the profile.1015            market: Loaded market borrowed from the caller; it must match the run/source prefix.1016            source: Detached prepared-source metadata matching the saved draft and initial1017                account.1018            log_path: Absolute path for a new JSON activity log. None chooses the default1019                local path for this run.1020            clock: Optional trusted shared experiment clock for test/advanced composition;1021                normal callers omit it.1022            execution_mode: Required playback mode: controlled for caller-driven policy1023                execution, live for background execution. Agent currently uses1024                background 1x in either mode.10251026        Returns:1027            AgentDecisionRunner: Ready child; source/account bindings checked before assembly.10281029        Raises:1030            ContractError: If an identity, configuration or lifecycle precondition is invalid.1031        """1032        self._resources.check_open()1033        from sim_platform.domain.experiment import validate_execution_mode10341035        source = dict(1036            self._validate_agent_market(market, source),1037            execution_mode=validate_execution_mode(execution_mode),1038        )1039        binding = self._operations.create_agent_run(profile, experiment_id, source)1040        return self._assemble_agent_runner(1041            profile,1042            binding,1043            market,1044            log_path,1045            clock,1046            execution_mode=execution_mode,1047            agent_factory=agent_factory,1048        )10491050    def _new_agent_experiment_run(1051        self,1052        profile: str,1053        account: str,1054        agent_id: str,1055        revision: int,1056        market: PreparedSession,1057        settings: JsonObject,1058        source: JsonObject,1059        execution_config: Optional[ExecutionConfig] = None,1060        log_path: Optional[PathInput] = None,1061        clock: Optional[SharedExperimentClock] = None,1062        *,1063        execution_mode: ExecutionMode,1064        agent_factory: Optional[AgentFactory] = None,1065    ) -> AgentDecisionRunner:1066        """Save the agent experiment choices and its run, then connect the runner.10671068        The draft and run are saved together before process assembly. If assembly fails,1069        the failed-start cleanup handles the created run. This is the internal setup path1070        used when the caller supplies all experiment choices at once.10711072        Args:1073            agent_factory: Optional trusted, spawn-picklable create_agent(context) callable.1074                Advanced Python composition hook. Normal callers omit it: configured Agents1075                use the template; imported Agents load their saved source and ready environment.1076            profile: Profile ID selecting whose saved data and account to use.1077            account: Account ID to trade with; the account must belong to profile.1078            agent_id: Registered Agent definition ID, not a maker or run ID.1079            revision: Positive saved Agent revision number.1080            market: Loaded market borrowed from the caller; it must match the run/source prefix.1081            settings: Caller-owned experiment settings; policy methods allow defaults, Agent1082                requires a complete settings object.1083            source: Detached prepared-source metadata matching the selected settings and market.1084            execution_config: Rules for order validation and fills. None uses the default1085                ExecutionConfig.1086            log_path: Absolute path for a new JSON activity log. None chooses the default1087                local path for this run.1088            clock: Optional trusted shared experiment clock for test/advanced composition;1089                normal callers omit it.1090            execution_mode: Required playback mode: controlled for caller-driven policy1091                execution, live for background execution. Agent currently uses1092                background 1x in either mode.10931094        Returns:1095            AgentDecisionRunner: Ready child; setup failures compensate the created run.10961097        Raises:1098            ContractError: If an identity, configuration or lifecycle precondition is invalid.1099        """1100        self._resources.check_open()1101        from sim_platform.domain.experiment import validate_execution_mode11021103        source = dict(1104            self._validate_agent_market(market, source),1105            execution_mode=validate_execution_mode(execution_mode),1106        )1107        binding = self._operations.create_agent_experiment_run(1108            profile, account, agent_id, revision, settings, source, execution_config1109        )1110        return self._assemble_agent_runner(1111            profile,1112            binding,1113            market,1114            log_path,1115            clock,1116            execution_mode=execution_mode,1117            agent_factory=agent_factory,1118        )11191120    def open_agent_run(1121        self,1122        profile: str,1123        experiment_id: str,1124        market: PreparedSession,1125        *,1126        source: JsonObject,1127        log_path: Optional[PathInput] = None,1128        clock: Optional[SharedExperimentClock] = None,1129        execution_mode: ExecutionMode,1130        agent_factory: Optional[AgentFactory] = None,1131    ) -> AgentDecisionRunner:1132        """Turn a saved agent experiment draft into a ready decision runner.11331134        Use this only when you have already called prepare_agent_experiment() and prepared1135        the market yourself. The draft chooses the agent, account and settings. This method1136        checks that the account still matches the draft and that source describes the market1137        and its starting position, then creates the run and connects the agent components.11381139        Agent, Tools and scheduling processes are prepared during this call. The returned1140        runner is ready, but playback has not started. Agent runs currently use background1141        1x playback in either execution mode. Platform closes the runner; you must keep the1142        supplied market open until the runner closes. For complete setup use open_experiment().11431144        Args:1145            agent_factory: Optional trusted, spawn-picklable create_agent(context) callable.1146                Advanced Python composition hook. Normal callers omit it: configured Agents1147                use the template; imported Agents load their saved source and ready environment.1148            profile: Profile ID selecting whose saved data and account to use.1149            experiment_id: Saved Agent experiment draft ID owned by the profile.1150            market: Loaded market borrowed from the caller; it must match the run/source prefix.1151            source: Detached matching metadata: symbol, source_manifest_ref, start_origin1152                (sequence/time_ns), prepared descriptor and optional experiment_start_ns.1153            log_path: Absolute path for a new JSON activity log. None chooses the default1154                local path for this run.1155            clock: Optional trusted shared experiment clock for test/advanced composition;1156                normal callers omit it.1157            execution_mode: Required playback mode: controlled for caller-driven policy1158                execution, live for background execution. Agent currently uses1159                background 1x in either mode.11601161        Returns:1162            AgentDecisionRunner: Ready background runner; pipeline state is ready and Play has1163            not started.11641165        Raises:1166            ContractError: If an identity, configuration or lifecycle precondition is invalid.11671168        Example:1169            runner = app.open_agent_run(profile_id, draft_id, market,1170                source=source_metadata, execution_mode='live')1171            runner.play()1172            runner.close()1173        """1174        runner = self._new_agent_run(1175            profile,1176            experiment_id,1177            market,1178            source=source,1179            log_path=log_path,1180            clock=clock,1181            execution_mode=execution_mode,1182            agent_factory=agent_factory,1183        )1184        runner.on_close(lambda: self._resources.remove(runner))1185        return self._resources.add(runner, shutdown_first=True)11861187    def open_research(1188        self,1189        *,1190        method: ExperimentMethod = 'human',1191        library: Optional[PathInput] = None,1192        agent_factory: Optional[AgentFactory] = None,1193    ) -> ResearchController:1194        """Create an empty workspace for preparing and controlling an experiment.11951196        Use this when your UI lets someone choose data and settings in separate steps. The1197        returned ResearchController holds those choices and later controls the experiment.1198        At this point it has no market, run or decision runner, and no child process starts.11991200        Call create_experiment() to prepare everything in one call, or use the controller's1201        preparation methods to show progress. Choose execution_mode when creating the1202        experiment. If you already have all the inputs, open_experiment() performs these1203        same steps for you. Platform tracks the controller and closes it during shutdown.12041205        Args:1206            agent_factory: Optional trusted, spawn-picklable create_agent(context) callable.1207                Advanced Python composition hook. Normal callers omit it: configured Agents1208                use the template; imported Agents load their saved source and ready environment.1209            method: Who makes decisions: human for manual input, rule for the built-in rule1210                policy, hold for the hold policy, model for a user's model file (Controlled1211                mode only; see docs/user-guide/model-policies.md), or agent for a saved1212                agent definition.1213            library: Path to the compiled market-data library. Usually omit this to use1214                the configured or bundled library.12151216        Returns:1217            ResearchController: AgentResearchController for agent, otherwise1218            PolicyResearchController. market, runner and run_id are None.12191220        Raises:1221            ContractError: If an identity, configuration or lifecycle precondition is invalid.12221223        Example:1224            research = app.open_research(method='human')1225            research.create_experiment(profile_id, account_id, source=source_path,1226                method='human', execution_mode='controlled')1227            research.step()1228            research.stop()1229            research.close()1230        """1231        self._resources.check_open()1232        if agent_factory is not None and (method != 'agent' or not callable(agent_factory)):1233            raise ContractError('agent_factory requires method=agent and a trusted callable')1234        from functools import partial12351236        controller: ResearchController1237        common: Dict[str, Any] = dict(1238            market_factory=lambda symbol, book=None, bar_origin=None: self._new_research_market(1239                symbol,1240                library=library,1241                bar_origin=bar_origin,1242                **(dict(depth=book['depth'], bar_spread=book['spread']) if book else {}),1243            ),1244            files=self._dataset_files,1245            export_writer=self._export_writer,1246        )1247        if method == 'agent':1248            from sim_platform.research.agent_controller import AgentResearchController12491250            controller = AgentResearchController(1251                self._operations,1252                **common,1253                agent_factory=partial(self._new_agent_run, agent_factory=agent_factory),1254                agent_experiment_factory=partial(1255                    self._new_agent_experiment_run, agent_factory=agent_factory1256                ),1257            )1258        elif method in ('human', 'rule', 'hold', 'model'):1259            from sim_platform.research.policy_controller import PolicyResearchController12601261            controller = PolicyResearchController(1262                self._operations,1263                **common,1264                runner_factory=self._new_runner,1265                live_runner_factory=self._new_live_policy_runner,1266            )1267        else:1268            raise ContractError('unknown research method')1269        controller.on_close(lambda: self._resources.remove(controller))1270        return self._resources.add(controller, shutdown_first=True)12711272    def open_experiment(1273        self,1274        profile: str,1275        account: str,1276        *,1277        source: Union[PathInput, Sequence[PathInput]],1278        method: ExperimentMethod = 'human',1279        settings: Optional[JsonObject] = None,1280        agent_id: Optional[str] = None,1281        revision: Optional[int] = None,1282        execution_config: Optional[ExecutionConfig] = None,1283        log_path: Optional[PathInput] = None,1284        library: Optional[PathInput] = None,1285        clock: Optional[SharedExperimentClock] = None,1286        execution_mode: ExecutionMode,1287        agent_factory: Optional[AgentFactory] = None,1288        book: Optional[Dict[str, int]] = None,1289        allow_short: bool = False,1290    ) -> ResearchController:1291        """Prepare a trading experiment so the caller can start it with play().12921293        Use this when you already know the account, market file and decision method. The1294        method prepares the historical data, saves a run record, and connects the decision1295        runner and trading components. It returns a controller for playing, pausing, stopping1296        and inspecting this experiment. The call waits for preparation; use open_research()1297        if your UI needs to show preparation progress instead.12981299        The experiment is ready when this returns, but its clock has not started. For human1300        or rule policies, Controlled lets the caller advance execution and Live runs it in1301        the background. Agent execution currently runs in the background at 1x. A saved run1302        can already say 'running' while its controller is ready or paused; that database1303        field only tells you whether the run has ended.13041305        Platform closes the controller, and the controller closes its market and runner.1306        If setup fails, partial resources are closed and any created run is cleaned up.1307        Agent setup needs a saved agent revision and complete settings. A configured1308        agent uses the built-in prompt/tool template. Call configure_experiment_model()1309        before Play to enable it; without model setup it waits without consuming work.1310        The template preserves context across rounds and explicitly finishes or waits.13111312        Args:1313            agent_factory: Optional trusted, spawn-picklable create_agent(context) callable.1314                Advanced Python composition hook. Normal callers omit it: configured Agents1315                use the template; imported Agents load their saved source and ready environment.1316            profile: Profile ID selecting whose saved data and account to use.1317            account: Account ID to trade with; the account must belong to profile.1318            source: Source file path for experiment preparation.1319            method: Who makes decisions: human for manual input, rule for the built-in rule1320                policy, hold for the hold policy, model for a user's model file (Controlled1321                mode only; see docs/user-guide/model-policies.md), or agent for a saved1322                agent definition.1323            settings: Caller-owned experiment settings; policy methods allow defaults, Agent1324                requires a complete settings object. Policy settings include start_mode,1325                start_time_ns and, for a custom start on a price-bar recording that covers1326                several days, start_date ('YYYY-MM-DD'; start_time_ns is then a time of day).1327            agent_id: Registered Agent definition ID, not a maker or run ID.1328            revision: Positive saved Agent revision number.1329            execution_config: Rules for order validation and fills. None uses the default1330                ExecutionConfig.1331            log_path: Absolute path for a new JSON activity log. None chooses the default1332                local path for this run.1333            library: Path to the compiled market-data library. Usually omit this to use1334                the configured or bundled library.1335            clock: Optional trusted shared experiment clock for test/advanced composition;1336                normal callers omit it.1337            execution_mode: Required playback mode: controlled for caller-driven policy1338                execution, live for background execution. Agent currently uses1339                background 1x in either mode.1340            book: For a price-bar (.csv) recording only: the synthetic book's spread1341                (best ask minus best bid, integer money in whole cents; 200 is $0.02, the1342                default) and depth (levels per side, 1..100; default 5), as1343                {'spread': 300, 'depth': 10}. Recorded in the prepared manifest. See1344                docs/reference/price-bars.md.1345            allow_short: Let sales go beyond the shares held, under the margin rule in1346                docs/reference/orders.md, which is saved with the run. Manual, rule, hold1347                and model methods only; default False.13481349        Returns:1350            ResearchController: The object used to control this experiment. Its market data1351            is prepared, its run is saved, and its decision runner is connected.1352            preparation.status is ready; call play() to start the clock.13531354        Raises:1355            ContractError: If options, ownership, source coverage or binding are invalid.1356            OSError: If source/prepared storage is unavailable; native/import/child failures propagate.13571358        Example:1359            experiment = app.open_experiment(profile_id, account_id,1360                source=source_path, method='human', execution_mode='live')1361            # The experiment is ready here; the market clock has not started.1362            experiment.play()1363            experiment.pause()1364            experiment.play()  # Resume.1365            experiment.stop()1366            experiment.close()1367        """1368        from sim_platform.domain.experiment import validate_execution_mode13691370        validate_execution_mode(execution_mode)1371        experiment = self.open_research(method=method, library=library, agent_factory=agent_factory)1372        try:1373            if allow_short and method == 'agent':1374                raise ContractError('short selling is not available for Agent experiments yet')1375            if allow_short and method != 'agent':1376                settings = dict(settings or {}, allow_short=True)1377            if book is not None and method != 'agent':1378                settings = dict(settings or {}, book=dict(book))1379            elif book is not None:1380                # Select the source with its book; the Agent setup keeps the selection.1381                symbol = str((settings or {}).get('symbol', 'AAPL'))1382                experiment.begin_prepare(cast('PathInput', source), symbol, book=book)1383                experiment.wait_for_preparation()1384            experiment.create_experiment(1385                profile,1386                account,1387                # A list of sources (one per symbol) is read by the policy controller.1388                source=cast('PathInput', source),1389                method=method,1390                settings=settings,1391                agent_id=agent_id,1392                revision=revision,1393                execution_config=execution_config,1394                log_path=log_path,1395                clock=clock,1396                execution_mode=execution_mode,1397            )1398            return experiment1399        except Exception as exc:1400            cleanup_after_error(exc, experiment.close)1401            raise14021403    def open_agent_experiment(1404        self,1405        profile: str,1406        account: str,1407        agent_id: str,1408        revision: int,1409        *,1410        source: PathInput,1411        settings: JsonObject,1412        execution_config: Optional[ExecutionConfig] = None,1413        log_path: Optional[PathInput] = None,1414        library: Optional[PathInput] = None,1415        clock: Optional[SharedExperimentClock] = None,1416        execution_mode: ExecutionMode,1417        agent_factory: Optional[AgentFactory] = None,1418    ) -> AgentResearchController:1419        """Prepare an agent trading experiment from a saved agent revision.14201421        Use this convenience form when the decision method is always agent. agent_id and1422        revision choose its saved definition; account, source and settings choose this test.1423        It calls open_experiment(method='agent') and returns the same kind of ready controller.1424        There is no separate experiment workflow behind this method.14251426        Preparation finishes before the call returns. Call play() to start. Platform closes1427        the controller and its resources. See open_experiment() for supported playback modes1428        and cleanup behavior.14291430        Args:1431            agent_factory: Optional trusted, spawn-picklable create_agent(context) callable.1432                Advanced Python composition hook. Normal callers omit it: configured Agents1433                use the template; imported Agents load their saved source and ready environment.1434            profile: Profile ID selecting whose saved data and account to use.1435            account: Account ID to trade with; the account must belong to profile.1436            agent_id: Registered Agent definition ID, not a maker or run ID.1437            revision: Positive saved Agent revision number.1438            source: Source file path for experiment preparation.1439            settings: Caller-owned experiment settings; policy methods allow defaults, Agent1440                requires a complete settings object.1441            execution_config: Rules for order validation and fills. None uses the default1442                ExecutionConfig.1443            log_path: Absolute path for a new JSON activity log. None chooses the default1444                local path for this run.1445            library: Path to the compiled market-data library. Usually omit this to use1446                the configured or bundled library.1447            clock: Optional trusted shared experiment clock for test/advanced composition;1448                normal callers omit it.1449            execution_mode: Required playback mode: controlled for caller-driven policy1450                execution, live for background execution. Agent currently uses1451                background 1x in either mode.14521453        Returns:1454            AgentResearchController: The same ready result as open_experiment(method="agent");1455            no Play or model request yet.14561457        Raises:1458            ContractError: If an identity, configuration or lifecycle precondition is invalid.14591460        Example:1461            experiment = app.open_agent_experiment(profile_id, account_id, agent_id, revision,1462                source=source_path, settings=agent_settings, execution_mode='live')1463        """1464        # method='agent' always opens an AgentResearchController.1465        return cast(1466            'AgentResearchController',1467            self.open_experiment(1468                profile,1469                account,1470                source=source,1471                method='agent',1472                settings=settings,1473                agent_id=agent_id,1474                revision=revision,1475                execution_config=execution_config,1476                log_path=log_path,1477                library=library,1478                clock=clock,1479                execution_mode=execution_mode,1480                agent_factory=agent_factory,1481            ),1482        )14831484    def evaluation(1485        self,1486        profile_id: str,1487        entries: Dict[str, List[str]],1488        *,1489        baseline: Optional[str] = None,1490        metric: str = 'total_return',1491        seed: int = 2026,1492        resamples: int = 10_000,1493        training_cutoffs: Optional[Dict[str, str]] = None,1494        token_prices: Optional[Dict[str, float]] = None,1495        trials: Optional[Dict[str, int]] = None,1496    ) -> JsonObject:1497        """Compare saved runs of Agents and baselines with confidence intervals and tests.14981499        Group finished runs into named entries, for example several runs of one Agent1500        revision and one run of a rule. Every run must have traded the same market with the1501        same starting cash and execution settings; otherwise the call fails and names the1502        difference. Reading saved runs does not start or change any experiment.15031504        Each entry gets every figure in docs/user-guide/evaluation.md with a 95% bootstrap1505        interval of its mean. With a baseline, every other entry is tested against it on1506        ``metric``: difference in means, its interval and a two-sided permutation p-value,1507        Holm-adjusted across entries. The same runs and seed always give the same report.15081509        Args:1510            profile_id: Profile that owns the runs.1511            entries: Entry name to the ids of its finished runs, at most 20 entries.1512            baseline: Name of the entry the others are tested against; None for figures only.1513            metric: Figure tested against the baseline, such as 'total_return' or1514                'sharpe_ratio'.1515            seed: Seed of the resampling generator, saved in the report.1516            resamples: Bootstrap and permutation resamples, 100 to 1,000,000.1517            training_cutoffs: Entry name to the training-data cutoff date (YYYY-MM-DD)1518                of the model its Agent runs used, to flag runs on dates it may have seen.1519            token_prices: {'input': ..., 'output': ...} in USD per million tokens, to1520                price Agent runs' model usage; None leaves model_cost empty.1521            trials: Entry name to how many configurations (prompts, parameters, Agent1522                revisions) were tried before keeping this one. It deflates that entry's1523                Sharpe ratio for the search. An entry whose runs all come from one Agent1524                defaults to that Agent's number of saved revisions; others to one trial.1525                The report's ``trial_sources`` says where each count came from.15261527        Returns:1528            dict: A detached 'agent-evaluation-v1' report.15291530        Raises:1531            ContractError: If a run is missing, not finished or not comparable, or an1532                argument is invalid.15331534        Example:1535            report = app.evaluation(profile_id, {'Agent': agent_runs, 'Rule': [rule_run]},1536                                    baseline='Rule')1537        """1538        self._resources.check_open()1539        from sim_platform.research.evaluation import (1540            agent_model_usage,1541            evaluate_reports,1542            is_agent_run,1543            memorisation_flags,1544        )1545        from sim_platform.research.reports import run_report15461547        if not isinstance(entries, dict):1548            raise ContractError('entries must map entry names to run ids')1549        reports: Dict[str, List[Dict[str, Any]]] = {}1550        for name, run_ids in entries.items():1551            if not isinstance(run_ids, list) or not all(isinstance(r, str) for r in run_ids):1552                raise ContractError(f'entry {name!r} must list run ids')1553            reports[name] = []1554            for run_id in run_ids:1555                report = run_report(self, profile_id, run_id)1556                if report['run']['status'] == 'running':1557                    raise ContractError(f'run {run_id} has not finished')1558                if is_agent_run(report):1559                    report['model_usage'] = agent_model_usage(1560                        self.agent_log_archive(profile_id, run_id)1561                    )1562                reports[name].append(report)1563        cutoffs = training_cutoffs or {}1564        if not isinstance(cutoffs, dict) or set(cutoffs) - set(entries):1565            raise ContractError('training_cutoffs must map entry names to dates')1566        flags = {1567            report['run']['id']: memorisation_flags(report, cutoffs.get(name))1568            for name, group in reports.items()1569            for report in group1570        }1571        counted = self._revision_trials(profile_id, reports)1572        given = dict(trials or {})1573        result = evaluate_reports(1574            reports,1575            baseline=baseline,1576            metric=metric,1577            seed=seed,1578            resamples=resamples,1579            flags=flags,1580            token_prices=token_prices,1581            trials=dict(counted, **given),1582        )1583        result['trial_sources'] = {1584            name: 'given' if name in given else 'agent revisions' if name in counted else 'one'1585            for name in reports1586        }1587        return result15881589    def _revision_trials(1590        self, profile_id: str, reports: Dict[str, List[Dict[str, Any]]]1591    ) -> Dict[str, int]:1592        """Trials counted from saved revisions for entries whose runs share one Agent.15931594        Every saved revision is a configuration someone tried, so the latest revision1595        number is a floor on the search behind that Agent.1596        """1597        counted: Dict[str, int] = {}1598        for name, group in reports.items():1599            ids = {1600                (((r['run'].get('config') or {}).get('agent') or {}).get('definition') or {}).get(1601                    'agent_id'1602                )1603                for r in group1604            }1605            if len(ids) == 1 and None not in ids:1606                counted[name] = int(self.agent(profile_id, str(ids.pop()))['revision'])1607        return counted16081609    def split_recording(1610        self,1611        source: PathInput,1612        output: PathInput,1613        *,1614        train_days: int,1615        test_days: int,1616        step_days: Optional[int] = None,1617        gap_days: int = 0,1618        anchored: bool = False,1619    ) -> List[JsonObject]:1620        """Cut a price-bar recording into walk-forward train and test files.16211622        Tune on each window's training file, then evaluate only on its test file, for1623        example with ``open_batch().evaluate_suite(test_files, entries)``. No test date1624        comes before the end of its training window. Reading and writing files does not1625        change any experiment.16261627        Args:1628            source: A price-bar CSV recording.1629            output: Folder for the window files, created when missing.1630            train_days: Trading dates per training window (the first one when anchored).1631            test_days: Trading dates per test window.1632            step_days: How far each window moves; defaults to test_days.1633            gap_days: Dates skipped between training and test, for labels that look ahead.1634            anchored: Keep every training window starting at the first date.16351636        Returns:1637            list: Per window, ``train`` and ``test`` paths with ``train_dates`` and1638                ``test_dates`` ([first, last]).16391640        Raises:1641            ContractError: If the file is unreadable or too short for one window.16421643        Example:1644            windows = app.split_recording(source_path, folder, train_days=250, test_days=60)1645        """1646        from sim_platform.research.walk_forward import split_recording16471648        return split_recording(1649            source,1650            output,1651            train_days=train_days,1652            test_days=test_days,1653            step_days=step_days,1654            gap_days=gap_days,1655            anchored=anchored,1656        )16571658    def disguise_recording(1659        self,1660        source: PathInput,1661        output: Optional[PathInput] = None,1662        *,1663        start_date: str = '2100-01-04',1664        price_scale: Optional[float] = None,1665        seed: int = 2026,1666        news: Optional[PathInput] = None,1667        fundamentals: Optional[PathInput] = None,1668        names: Optional[List[str]] = None,1669        symbol: str = 'ASSET1',1670        alias: str = 'the company',1671    ) -> JsonObject:1672        """Write a disguised copy of a price-bar CSV so a model cannot recall its market.16731674        Dates move by whole weeks into the future (weekdays kept) and every price is1675        multiplied by one factor, rounded to the cent; volumes are kept and other columns1676        are dropped. Use the copy as the recording for every method you compare, and give1677        the experiment a neutral symbol such as 'ASSET1'. Evaluations flag Agent runs on1678        future dates as 'disguised'. The original file is not changed.16791680        Args:1681            source: Price-bar CSV file to disguise.1682            output: Where to write the copy; default a neutral name under this Platform's1683                directory, in 'disguised/'.1684            start_date: Earliest first date of the copy (YYYY-MM-DD).1685            price_scale: Factor applied to prices, 0.01 to 100; None draws one from [0.5, 2]1686                with ``seed``.1687            seed: Seed for the drawn factor.1688            news: A news JSON file to disguise with the same date shift; headlines and1689                periods have ``names`` replaced by ``alias`` and their dates moved.1690            fundamentals: A fundamentals CSV to disguise the same way; its rows take1691                ``symbol`` and its dates move with the prices.1692            names: Company names and tickers to hide in text, such as ['Apple', 'AAPL'].1693            symbol: The neutral symbol for disguised fundamentals rows.1694            alias: The words that replace each listed name.16951696        Returns:1697            dict: The mapping: 'source', 'output', 'first_date', 'disguised_first_date',1698                'shift_days' and 'price_scale', plus 'news_output' and1699                'fundamentals_output' when those files were given. Keep it away from the1700                Agent.17011702        Raises:1703            ContractError: If the file is not a valid price-bar CSV or an argument is invalid.17041705        Example:1706            mapping = app.disguise_recording('aapl.csv')1707            experiment = app.open_experiment(profile, account, source=mapping['output'],1708                                             settings=dict(symbol='ASSET1'))1709        """1710        self._resources.check_open()1711        import hashlib17121713        from sim_platform.market.prepared.bars import is_bar_source1714        from sim_platform.market.prepared.disguise import disguise_price_bars17151716        path = Path(source)1717        if not is_bar_source(path):1718            raise ContractError('only price-bar CSV recordings can be disguised')1719        if output is None:1720            digest = hashlib.sha256(1721                f'{path.resolve()}|{start_date}|{price_scale}|{seed}'.encode()1722            ).hexdigest()[:12]1723            output = self.directory / 'disguised' / f'disguised-{digest}.csv'1724        mapping = dict(1725            disguise_price_bars(1726                path, Path(output), start_date=start_date, price_scale=price_scale, seed=seed1727            )1728        )1729        from sim_platform.market.prepared.disguise_text import (1730            disguise_fundamentals,1731            disguise_news,1732        )17331734        base = Path(mapping['output'])1735        if news is not None:1736            target = base.with_name(base.stem + '-news.json')1737            disguise_news(Path(news), target, mapping['shift_days'], names or [], alias)1738            mapping['news_output'] = str(target)1739        if fundamentals is not None:1740            target = base.with_name(base.stem + '-fundamentals.csv')1741            disguise_fundamentals(1742                Path(fundamentals), target, mapping['shift_days'], symbol, names or [], alias1743            )1744            mapping['fundamentals_output'] = str(target)1745        return mapping17461747    def run_sweep(1748        self,1749        paths: List[PathInput],1750        base: JsonObject,1751        grid: Dict[str, List[Any]],1752        *,1753        metric: str = 'total_return',1754        library: Optional[PathInput] = None,1755        **arguments: Any,1756    ) -> JsonObject:1757        """Run a grid of parameters or prompts and return a results table.17581759        ``base`` is one suite entry, as for ResearchBatch.evaluate_suite(): a rule1760        (``policy``, ``quantity``, ``hold_ns``), a model file (``model``) or a saved Agent1761        (``agent_id``, ``revision``, ``settings``, ``model``). ``grid`` names entry fields1762        by dotted path and lists values for each, for example ``{'quantity': [1, 5],1763        'hold_ns': [60e9, 600e9]}`` or ``{'model.temperature': [0, 0.7]}``. For an Agent,1764        the field ``prompt`` lists task prompts: each is saved as a new revision of the1765        Agent (so evaluations count it as a trial) and run as its own combination.17661767        Every combination runs ``repetitions`` times on every recording, each run on a new1768        account, so a sweep of Agents takes as long as all its windows. Each entry's1769        deflated Sharpe ratio counts every combination as a trial, since picking the1770        best cell is itself a search. Pass the table to research.sweeps.heatmap() and1771        render_heatmap_svg() for a heat map.17721773        Args:1774            paths: Recordings to run on (1 to 20).1775            base: The suite entry every combination starts from.1776            grid: Swept fields and their values (at most 200 combinations).1777            metric: The figure tabulated and ranked (see evaluation metrics).1778            library: Optional native library for the batch.1779            **arguments: Further evaluate_suite() arguments (``profile``, ``cash``,1780                ``fee_per_share``, ``seed``, ``model_provider``, ``concurrency``, ...).17811782        Returns:1783            JsonObject: ``format`` 'market-lab-sweep-v1', ``metric``, ``grid``,1784            ``combinations``, ``rows`` (``name``, ``parameters``, ``mean`` and per1785            recording ``mean``, ``n``, ``interval``, ``sharpe``, ``deflated_sharpe``,1786            ``run_ids``), ``best`` and the underlying ``suites``.17871788        Raises:1789            ContractError: If the grid or an entry is invalid, or a prompt sweep is not1790                for an Agent entry with a ``profile``.17911792        Example:1793            result = app.run_sweep([recording], dict(name='rule', quantity=1),1794                                   dict(quantity=[1, 5, 10], hold_ns=[60e9, 600e9]))1795            from sim_platform.research.sweeps import heatmap, render_heatmap_svg1796            svg = render_heatmap_svg(heatmap(result['rows'], 'quantity', 'hold_ns'))1797        """1798        from sim_platform.research.sweeps import run_sweep17991800        grid = dict(grid)1801        prompts: Dict[int, str] = {}1802        if 'prompt' in grid:1803            prompts = self._prompt_revisions(base, grid.pop('prompt'), arguments.get('profile'))1804            grid['revision'] = list(prompts)1805        with self.open_batch(library=library) as batch:1806            result = run_sweep(batch, paths, base, grid, metric=metric, **arguments)1807        for row in result['rows']:1808            if row['parameters'].get('revision') in prompts:1809                row['parameters']['prompt'] = prompts[row['parameters']['revision']]1810        if prompts:1811            result['prompts'] = {str(k): v for k, v in prompts.items()}1812        return result18131814    def _prompt_revisions(1815        self, base: JsonObject, prompts: List[Any], profile_id: Optional[str]1816    ) -> Dict[int, str]:1817        """Save each prompt as a new revision of the base Agent; map revision to prompt."""1818        if base.get('policy') != 'agent' or not profile_id:1819            raise ContractError('a prompt sweep needs an Agent entry and the profile')1820        if not isinstance(prompts, list) or not prompts:1821            raise ContractError('prompt needs a list of task prompts')1822        (agent_id, revision) = (base.get('agent_id'), base.get('revision'))1823        if not isinstance(agent_id, str) or not isinstance(revision, int):1824            raise ContractError('a prompt sweep needs the Agent entry\'s agent_id and revision')1825        saved = self.agent(profile_id, agent_id, revision)1826        latest = self.agent(profile_id, agent_id)['revision']1827        revisions: Dict[int, str] = {}1828        for prompt in prompts:1829            if not isinstance(prompt, str) or not prompt.strip():1830                raise ContractError('each prompt must be nonempty text')1831            definition = dict(saved['definition'], initial_prompt=prompt, revision=str(latest + 1))1832            latest = self.update_agent(profile_id, agent_id, latest, definition)['revision']1833            revisions[latest] = prompt1834        return revisions18351836    def open_batch(self, *, library: Optional[PathInput] = None) -> ResearchBatch:1837        """Create a helper for evaluating policies in separate experiments.18381839        Use evaluate() for one policy evaluation or compare() to compare results. Each1840        evaluation uses an independent account and the same market-preparation workflow as1841        an ordinary research experiment. Creating this helper does not run an evaluation.18421843        library selects the native market library used to prepare data. Collect the results1844        of your evaluations, then close the batch. Platform also closes it during shutdown.18451846        Args:1847            library: Path to the compiled market-data library. Usually omit this to use1848                the configured or bundled library.18491850        Returns:1851            ResearchBatch: No evaluation started; owns no active evaluation controller yet.18521853        Raises:1854            ContractError: If an identity, configuration or lifecycle precondition is invalid.18551856        Example:1857            batch = app.open_batch()1858            result = batch.evaluate(source_path, policy='rule')1859            batch.close()1860        """1861        self._resources.check_open()1862        from sim_platform.research.batch import ResearchBatch18631864        from functools import partial18651866        from sim_platform.research.batch import _evaluate_agent18671868        batch = ResearchBatch(1869            # Batch comparisons use the default (policy) method.1870            lambda: cast('PolicyResearchController', self.open_research(library=library)),1871            self.directory,1872            export_writer=self._export_writer,1873            agent_evaluator=partial(_evaluate_agent, self),1874        )1875        batch.on_close(lambda: self._resources.remove(batch))1876        return self._resources.add(batch)18771878    def open_datasets(1879        self, *, demo_source: Optional[Tuple[PathInput, Optional[PathInput]]] = None1880    ) -> DatasetLibrary:1881        """Open the catalog used to find and import local market data files.18821883        Use the returned DatasetLibrary to manage which datasets appear in the app. Opening1884        it may update an older folder-only catalog. If demo_source is supplied, that file is1885        registered by its path; it is not copied. Later, add(copy=True) can explicitly copy1886        an imported file.18871888        Listing or registering a file does not prepare its order book or create a trading1889        experiment. Platform keeps the catalog open until you close it or close Platform.18901891        Args:1892            demo_source: Optional (market_path, news_path) demonstration source pair; market is1893                registered by reference.18941895        Returns:1896            DatasetLibrary: Open catalog with saved preferences and entries loaded.18971898        Raises:1899            ContractError: If an identity, configuration or lifecycle precondition is invalid.19001901        Example:1902            datasets = app.open_datasets()1903            catalog = datasets.catalog()1904            datasets.close()1905        """1906        self._resources.check_open()1907        from sim_platform.research.datasets import DatasetLibrary19081909        library = DatasetLibrary(self._dataset_files, demo_source)1910        library.on_close(lambda: self._resources.remove(library))1911        return self._resources.add(library)19121913    def replay_prepared_operations(1914        self,1915        profile: str,1916        account: Optional[str],1917        log_path: PathInput,1918        *,1919        cancelled: Optional[Callable[[], bool]] = None,1920    ) -> PreparedReplayResult:1921        """Check a recorded experiment by executing its original trading operations again.19221923        Use this to verify the saved outcome without asking the agent or model to decide1924        again. Human, Rule and Agent logs use the same path. It reads a sealed operation1925        log and prepared market data, then runs original trading commands at their original1926        receipt times. Original Pause/Resume, model retries and waits are not re-executed.1927        Actual cancellations caused by the end of the experiment are reproduced.19281929        The destination must belong to profile and match the original starting balances,1930        holdings, fees and order history. The original run and its account are unchanged.1931        The destination account is modified. This call waits for replay to finish and saves1932        a new destination run. A failed replay can leave a stopped or failed destination run1933        for inspection.19341935        Args:1936            profile: Profile ID selecting whose saved data and account to use.1937            account: Matching destination account ID, or None to create a new clean cash1938                account. Prior holdings/history require an explicitly matching account.1939            log_path: Absolute path to a sealed current-format original-operation JSON log.1940            cancelled: Optional cooperative cancellation check, called between replay steps.19411942        Returns:1943            PreparedReplayResult: A dictionary identifying the new replay run, with1944            matched=True, the number of commands, financial comparison data,1945            replay=True and model_calls=0. operations contains original trading requests1946            in receipt order; events contains recomputed acceptance, rejection, fill and1947            cancellation events with time_ns. Original fills are comparison evidence only.1948            events_verified=True means every financial event matched the recorded list;1949            older compatible logs without that list report False and compare final state.19501951        Raises:1952            ContractError: If the log/artifact/initial account is unsupported or results differ.1953            OSError: If the log or artifact cannot be read.19541955        Example:1956            comparison = app.replay_prepared_operations(profile_id, replay_account_id, log_path)1957            assert comparison['matched']1958        """1959        from sim_platform.persistence.agent_log_files import read_agent_log1960        from .experiments.replay import replay19611962        self._resources.check_open()1963        archive = read_agent_log(log_path)1964        if account is None:1965            from sim_platform.replay.plan import decode_plan19661967            initial = decode_plan(archive)[0]['initial_account']1968            if (1969                initial['positions']1970                or initial['orders']1971                or initial['fees']1972                or initial['realized_pnl']1973            ):1974                raise ContractError(1975                    'select a destination account matching the original portfolio/history'1976                )1977            if cancelled is not None and cancelled():1978                raise ContractError('Replay cancelled')1979            account = self.create_account(profile, 'Replay · original operations', initial['cash'])1980        return cast(1981            PreparedReplayResult,1982            replay(1983                self._operations,1984                self._new_runner,1985                profile,1986                account,1987                archive,1988                cancelled=cancelled or (lambda: False),1989            ),1990        )19911992    def open_replay(self, *, library: Optional[PathInput] = None) -> ReplaySession:1993        """Create a manual replay session for previously loaded raw-source inputs.19941995        This is an advanced building block. The caller supplies already loaded replay inputs1996        and separate destination storage through the returned session. Platform tracks and1997        closes that session.19981999        To verify or recover a saved file-source run, normally use replay_run() instead. It2000        prepares the separate storage and handles cleanup for you.20012002        Args:2003            library: Path to the compiled market-data library. Usually omit this to use2004                the configured or bundled library.20052006        Returns:2007            ReplaySession: A session ready for manual replay setup. No recorded operation2008            has been replayed yet.20092010        Raises:2011            ContractError: If an identity, configuration or lifecycle precondition is invalid.20122013        Example:2014            session = app.open_replay()2015            # session.run(...) requires validated replay inputs and isolated storage.2016            session.close()2017        """2018        self._resources.check_open()2019        from sim_platform.replay.runner import ReplaySession20202021        def prepared_market(2022            symbol: str, depth: int, bar_spread: Optional[int], bar_origin: Optional[str] = None2023        ) -> PreparedSession:2024            return self._new_research_market(2025                symbol, depth=depth, library=library, bar_spread=bar_spread, bar_origin=bar_origin2026            )20272028        replay = ReplaySession(2029            self._operations,2030            market_factory=lambda symbol, depth: self._new_market(2031                symbol, depth=depth, library=library2032            ),2033            runner_factory=self._new_runner,2034            execution_factory=self._new_execution,2035            prepared_market_factory=prepared_market,2036        )2037        replay.on_close(lambda: self._resources.remove(replay))2038        return self._resources.add(replay)20392040    @classmethod2041    def replay_run(2042        cls,2043        directory: Optional[PathInput],2044        run_id: str,2045        destination: PathInput,2046        *,2047        library: Optional[PathInput] = None,2048        recover: bool = False,2049        policy_bindings: Optional[Dict[str, Policy]] = None,2050    ) -> Union[ReplayVerification, RecoveredRun]:2051        """Verify a saved file-source run, or rebuild it so it can continue.20522053        This class method works without an existing Platform. It reads the original database2054        and replays saved actions into a separate, empty destination directory. Verification2055        compares the recalculated results; it does not ask the original policy or model to2056        make new decisions. The original data is unchanged.20572058        With recover=False, it returns a verification dictionary and closes its temporary2059        resources. With recover=True, it rebuilds a supported interrupted run to its saved2060        checkpoint and returns a paused RecoveredRun that you must close. Recovery may need2061        compatible policy_bindings keyed by maker ID. Live and agent operation logs use2062        replay_prepared_operations() instead.20632064        Args:2065            directory: Existing source platform data directory containing the saved run.2066                None selects the per-OS-user default directory, as Platform() does.2067            run_id: Existing run ID owned by the selected profile.2068            destination: Empty isolated output directory; original source storage must be2069                separate.2070            library: Path to the compiled market-data library. Usually omit this to use2071                the configured or bundled library.2072            recover: False verifies a supported terminal run; True reconstructs a supported2073                interrupted run.2074            policy_bindings: Optional mapping of maker IDs to compatible Policy objects for2075                recovery.20762077        Returns:2078            ReplayVerification when recover=False, after isolated resources close. RecoveredRun2079            when recover=True, paused and still open; the caller owns it.20802081        Raises:2082            ContractError: If inputs/source identities, destination or recovery bindings are invalid.2083            OSError: If database, source or output paths cannot be accessed.20842085        Example:2086            verified = Platform.replay_run(source_directory, run_id, empty_destination)2087            assert verified['verified']2088            # For supported interrupted runs, use a different empty destination:2089            with Platform.replay_run(source_directory, interrupted_id, recovery_directory,2090                                     recover=True, policy_bindings=bindings) as recovered:2091                recovered.owner.play()2092        """2093        from contextlib import ExitStack2094        from dataclasses import asdict2095        from sim_platform.domain.json_values import copy_json2096        from sim_platform.application.use_cases.accounts import AccountService2097        from .replay_manifest import validate_source2098        from sim_platform.persistence.replay.storage import read_inputs, prepare_destination20992100        destination = Path(destination).resolve()2101        # None selects the same per-OS-user default as Platform(directory=None).2102        source = Path(directory).expanduser() if directory is not None else data_directory()2103        inputs = read_inputs(2104            source,2105            run_id,2106            recover=recover,2107            snapshot_reader=lambda repo, profile, account: copy_json(2108                asdict(AccountService(repo).snapshot(profile, account))2109            ),2110        )2111        validate_source(inputs['source_info'], library)2112        prepare_destination(source, run_id, destination, inputs)2113        with ExitStack() as resources:2114            app = resources.enter_context(cls(destination))2115            session = app.open_replay(library=library)2116            result = session.run(2117                inputs, run_id, destination, recover=recover, policy_bindings=policy_bindings2118            )2119            if recover:2120                # recover=True always produces a RecoveredRun.2121                cast('RecoveredRun', result).adopt_lifetime(resources.pop_all(), app)2122            return cast('Union[ReplayVerification, RecoveredRun]', result)21232124    def decision_runner(2125        self, profile_id: str, run_id: str, maker_id: str, market: MarketInput, policy: Policy2126    ) -> PolicyDecisionRunner:2127        """Connect a saved policy run to the policy and market that will execute it.21282129        Use this after create_decision_run() when assembling an experiment manually. The2130        policy must match the saved policy description, and the run and market must be at2131        their required starting state. The returned runner calls the policy for decisions2132        and sends its orders through the trading components.21332134        This runner executes synchronously when its methods are called. It owns its trading2135        session, but borrows your market: close the runner before closing that market.2136        Platform also tracks the runner. Use open_experiment() for automatic setup.21372138        Args:2139            profile_id: Profile ID returned by create_profile(); selects whose data to access.2140            run_id: Existing run ID owned by the selected profile.2141            maker_id: Maker ID with current command authority for the run.2142            market: Loaded market borrowed from the caller; it must match the run/source prefix.2143            policy: Strategy object implementing decisions.contracts.Policy. For an2144                existing run, its identity and settings must match the saved policy.21452146        Returns:2147            PolicyDecisionRunner: Ready to request decisions from the supplied policy.2148            It is connected to this run and market; playback has not started.21492150        Raises:2151            ContractError: If an identity, configuration or lifecycle precondition is invalid.21522153        Example:2154            runner = app.decision_runner(profile_id, run_id, maker_id, market, policy)2155            runner.step()2156            runner.close()2157        """2158        runner = self._new_runner(profile_id, run_id, maker_id, market, policy)2159        runner.on_close(lambda: self._resources.remove(runner))2160        return self._resources.add(runner)21612162    def abort_execution_run(self, profile_id: str, run_id: str) -> ExecutionSnapshot:2163        """Stop a saved execution run that no longer has an active executor.21642165        Use this as a recovery action, for example after the process that owned the run has2166        gone away. It obtains exclusive access to the account and performs the normal trading2167        finish steps. Completed fills stay in the account and the run record is kept.21682169        If a session or runner still owns the run, stop it through that object instead.21702171        Args:2172            profile_id: Profile ID returned by create_profile(); selects whose data to access.2173            run_id: Existing run ID owned by the selected profile.21742175        Returns:2176            ExecutionSnapshot: Final stopped financial state after cancellation of remaining2177            orders.21782179        Raises:2180            ContractError: If an identity, configuration or lifecycle precondition is invalid.21812182        Example:2183            final = app.abort_execution_run(profile_id, orphaned_run_id)2184            assert final.status == 'stopped'2185        """2186        return self._operations.abort_execution_run(profile_id, run_id)21872188    def decision_session(self, profile_id: str, run_id: str, maker_id: str) -> DecisionSession:2189        """Get a small object for recording intents and strategy state on a plain run.21902191        Use the returned DecisionSession to observe the account, record a proposed action,2192        and save or load your own policy state. It remembers the profile, run and maker IDs2193        so you do not need to pass them on each call. The maker's right to control the run2194        is checked when the session is created.21952196        A plain run has no trading engine attached: recording an intent does not check funds2197        or match an order. Execution and policy-configured runs must use their execution2198        session or runner instead. Keep Platform open while using this object; it has no2199        separate close method.22002201        Args:2202            profile_id: Profile ID returned by create_profile(); selects whose data to access.2203            run_id: Existing run ID owned by the selected profile.2204            maker_id: Maker ID with current command authority for the run.22052206        Returns:2207            DecisionSession: An object remembering this run and maker for later calls.2208            It shares Platform storage and creates no executor, thread or process.22092210        Raises:2211            ContractError: If an identity, configuration or lifecycle precondition is invalid.22122213        Example:2214            session = app.decision_session(profile_id, plain_run_id, maker_id)2215            current = session.observe()2216        """2217        self._operations.validate_authority(profile_id, run_id, maker_id)2218        return DecisionSession(self._operations, profile_id, run_id, maker_id)22192220    def close(self) -> None:2221        """Stop this platform's work and release the resources it created.22222223        Call this when the app is done, or let a with block call it automatically. Experiments,2224        processes and workers are closed before storage. This can wait while they finish2225        outstanding work or shut down. Markets borrowed through manual setup APIs remain2226        the caller's responsibility.22272228        Calling close() again after success is safe. If cleanup fails, the error is raised2229        and unresolved resources remain tracked so you can retry. closed becomes True when2230        shutdown starts, even if cleanup later fails.22312232        Returns:2233            None. The platform stops accepting new resources as soon as shutdown begins.22342235        Raises:2236            Exception: Child shutdown, financial finalization, storage or credential backend failure; retry after resolving it.22372238        Example:2239            app.close()2240            assert app.closed2241        """2242        if self.closed and not self._resources.has_roots:2243            return2244        storage = tuple(2245            [self._database_instance.close] if self._database_instance is not None else []2246        )2247        storage += (self._workspace.close,)2248        if self._credentials is not None:2249            storage += (self._credentials.close,)2250        try:2251            self._resources.close()2252        except Exception as exc:2253            if not self._resources.has_live_execution:2254                cleanup_after_error(exc, *storage)2255            raise2256        cleanup(*storage)22572258    def __enter__(self) -> Platform:2259        """Use this Platform inside a with block.22602261        The block receives the same Platform object. Leaving the block calls close(), so2262        experiments and workers are cleaned up even if the block raises an exception.2263        Entering is rejected if shutdown has already started.22642265        Returns:2266            Platform: This same instance.22672268        Raises:2269            ContractError: If an identity, configuration or lifecycle precondition is invalid.22702271        Example:2272            with Platform(storage_path) as app:2273                profiles = app.profiles()2274        """2275        self._resources.check_open()2276        return self22772278    def __exit__(self, *args: Any) -> None:2279        """Close the platform when its with block ends.22802281        This calls close() whether the block finished normally or raised an exception. It2282        does not suppress the block's exception. A cleanup failure can also raise an error.22832284        Args:2285            args: Exception type, exception value and traceback supplied by the with statement;2286                ignored, so exceptions are not suppressed.22872288        Returns:2289            None. Exceptions from the with block are not suppressed.22902291        Raises:2292            Exception: If resource or storage cleanup fails.2293        """2294        self.close()229522962297class DecisionSession:2298    """Record proposed actions and saved strategy state for one plain run.22992300    Obtain this object from Platform.decision_session(). It remembers which profile,2301    run and maker your calls refer to. It can read the account, record an intent and2302    save your own JSON state. An intent here is only a recorded proposal: this object2303    does not check available funds or execute orders against a market.23042305    For actual trading, use an execution session or decision runner. This object shares2306    its Platform's storage, so keep Platform open while using it.2307    """23082309    def __init__(2310        self, operations: ApplicationOperations, profile_id: str, run_id: str, maker_id: str2311    ) -> None:2312        """Remember which plain run and decision-maker this object will access.23132314        Platform.decision_session() supplies the shared operations and checks the IDs for2315        the caller. This constructor stores those references; it does not create a market,2316        thread or trading executor. The supplied operations remain owned by Platform.23172318        Args:2319            operations: Coordinator owned by Platform; no ownership is transferred.2320            profile_id: Owning profile ID, checked by the Platform factory.2321            run_id: Plain run whose intents/state this facade accesses.2322            maker_id: Maker with current command authority.23232324        Returns:2325            None. No thread, execution owner or market is created.2326        """2327        self.__operations = operations2328        self.__profile = profile_id2329        self.__run = run_id2330        self.__maker = maker_id23312332    def observe(self) -> AccountSnapshot:2333        """Read the current account state for this session's run.23342335        Use this before recording a proposed action if you need to inspect cash, holdings2336        or orders. It returns a snapshot for this call, not a live view. It does not advance2337        the market or make a decision.23382339        Returns:2340            AccountSnapshot: Detached current cash/positions/orders; no market cutoff2341            is captured and no decision or order is executed.23422343        Raises:2344            ContractError: If ownership/run identity is no longer valid.23452346        Example:2347            account = session.observe()2348            available_cash_before_reservations = account.cash2349        """2350        run = self.__operations.run(self.__profile, self.__run)2351        return self.__operations.snapshot(self.__profile, run["account_id"])23522353    def submit(self, intent: Intent, time_ns: int) -> str:2354        """Save a proposed buy or sell action as an intent on this plain run.23552356        The intent records what the decision-maker wanted to do and at what simulation2357        time. This method does not check funds or match a trade against the market. Its2358        returned string identifies the saved intent, not a filled order.23592360        Submitting the same client ID with identical content reuses the saved event.2361        Different content under that ID is rejected. Use a trading runner for actual orders.23622363        Args:2364            intent: Intent with shares and integer USD ten-thousandths limit price.2365            time_ns: Nonnegative simulation nanoseconds, not a wall-clock timestamp.23662367        Returns:2368            str: Persisted intent ID. This is not an acceptance/fill acknowledgement.2369            Identical client IDs/content reuse the ledger event; conflicts fail.23702371        Raises:2372            ContractError: If the run has execution settings, maker authority changed,2373                the intent is invalid or its timestamp moves backwards.23742375        Example:2376            intent_id = session.submit(Intent('request-1', 'AAPL', 'buy', 1, 1_000_000), 0)2377        """2378        return self.__operations._submit(self.__profile, self.__run, self.__maker, intent, time_ns)23792380    def save_state(self, value: JsonValue) -> None:2381        """Save a JSON value that your strategy can read on its next call.23822383        For example, a simple strategy can remember how many observations it has processed.2384        The value is stored for this plain run. Saving it does not place an order or produce2385        a market event. It must be JSON-compatible data, not an API key or a database object.23862387        Args:2388            value: JSON-compatible state; not an ORM object or credential container.23892390        Returns:2391            None. The state is committed without producing trades or market events.23922393        Raises:2394            ContractError: If maker authority is stale, JSON is invalid, or a2395                decision-configured run owns its journal through a Runner.23962397        Example:2398            session.save_state({'observations': 3})2399        """2400        self.__operations._policy_state(self.__profile, self.__run, self.__maker, value)24012402    def load_state(self) -> JsonValue:2403        """Read the strategy value previously saved for this plain run.24042405        Use this to continue your own strategy bookkeeping. Before anything has been saved,2406        the result is an empty dictionary. The result is data for this call; changing it does2407        not save changes unless you call save_state(). It is not an agent conversation history2408        or an automatic memory system.24092410        Returns:2411            JsonValue: Detached stored policy_state, initially an empty dictionary.2412            Does not include model context or create a memory system.24132414        Raises:2415            ContractError: If the run/profile identity is invalid.24162417        Example:2418            state = session.load_state()2419        """2420        return self.__operations.run(self.__profile, self.__run)["policy_state"]