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"]