agent.py
1"""Assemble one Agent runner from explicit Platform-owned capabilities.23No Platform instance enters this module. Assembly owns rollback until the4complete runner is returned; the controller then owns the runner.5"""67from __future__ import annotations89from typing import Any, Callable, Dict, Optional, Tuple, TYPE_CHECKING, Union10from .contracts import AgentAssemblyServices, AgentBinding, AgentLaunch11from sim_platform.domain.models import ContractError1213if TYPE_CHECKING:14 from sim_platform.decisions.agent.runner import AgentDecisionRunner15 from sim_platform.market.prepared.session import PreparedSession16 from sim_platform.experiments.scheduling.clock import SharedExperimentClock17 from os import PathLike18 from pathlib import Path1920 from sim_platform.agents.operation_log import AgentOperationLog21 from sim_platform.agents.tools.server.router import AgentTools22 from sim_platform.experiments.execution.session import ExperimentSession23 from sim_platform.experiments.scheduling.host import ExperimentRuntimeHandle24 from sim_platform.sdk import AgentFactory25from sim_platform.resources import cleanup_after_error2627NS_PER_SECOND = 1_000_000_000282930def require_bound_operation(payload: Any, position: Dict[str, str]) -> Any:31 """Setup cannot accept commands until bind_agent_tools installs the handler."""32 raise ContractError('agent tools are not bound')333435def create_agent_pipeline(36 execution_factory: Callable[..., Any],37 compose_pipeline: Callable[..., ExperimentSession],38 profile_id: str,39 run_id: str,40 maker_id: str,41 market: PreparedSession,42 *,43 end_ns: int,44 lag_limit_ns: int,45 clock: SharedExperimentClock,46 capacity: int,47 start_ns: int,48 lag_window_ns: int,49) -> ExperimentSession:50 """Create execution before Tools binding; failed setup can still drain output."""51 from sim_platform.experiments.execution.market import LocalMarketExecution52 from .agent_driver import AgentPipelineOutput5354 execution = execution_factory(profile_id, run_id, maker_id, market)55 try:56 pipeline = compose_pipeline(57 LocalMarketExecution(execution, market),58 market,59 end_ns=end_ns,60 lag_limit_ns=lag_limit_ns,61 sink=AgentPipelineOutput(),62 operation=require_bound_operation,63 clock=clock,64 capacity=capacity,65 start_ns=start_ns,66 lag_window_ns=lag_window_ns,67 )68 except Exception as exc:69 cleanup_after_error(exc, execution.close)70 raise71 pipeline.on_close(execution.close)72 return pipeline737475def load_run_fundamentals(config: Dict[str, Any], reader: Any, symbol: str) -> Any:76 """Load the run's fundamentals file, or None when the run has none.7778 A file or a folder of files, each read by market.fundamentals.load_fundamentals_path:79 EDGAR companyfacts JSON, a fundamentals CSV or an ALFRED vintage CSV. Publication dates are placed on the experiment80 timeline with the recording's first date, so the recording must carry dates.8182 Raises:83 ContractError: If the recording has no calendar or the file is invalid.84 """85 path = config.get('fundamentals_path')86 if not path:87 return None88 from sim_platform.domain.models import ContractError89 from sim_platform.market.fundamentals import load_fundamentals_path9091 calendar = (getattr(reader, 'manifest', None) or {}).get('calendar') or {}92 start = calendar.get('start_date')93 if not start:94 raise ContractError('fundamentals need a dated recording, such as a price-bar file')95 return load_fundamentals_path(path, symbol, start)969798def load_run_documents(config: Dict[str, Any]) -> Any:99 """Load the run's documents file for documents.search/read, or None without one."""100 path = config.get('documents_path')101 if not path:102 return None103 from sim_platform.market.documents import load_documents104105 return load_documents(path)106107108def bind_agent_tools(109 directory: Path,110 create_log: Callable[..., AgentOperationLog],111 archive_log: Callable[..., Any],112 commit_decision: Callable[..., Any],113 profile: str,114 experiment_id: str,115 binding: AgentBinding,116 pipeline: ExperimentSession,117 log_path: Optional[Union[str, PathLike[str]]],118 runtime: ExperimentRuntimeHandle,119) -> Tuple[AgentTools, AgentOperationLog]:120 """Wire read/trade capabilities and output at the pipeline setup boundary."""121 from sim_platform.agents.tools.server.router import AgentTools122 from sim_platform.agents.tools.trading.commands import TradingTools123 from .agent_driver import AgentToolCapture, AgentPipelineOutput124125 if log_path is None:126 from sim_platform.persistence.agent_log_files import default_agent_log_path127128 log_path = default_agent_log_path(directory, binding['run_id'])129 recorder = create_log(profile, experiment_id, binding['run_id'], log_path)130 queries = None131 try:132 from functools import partial133 from sim_platform.experiments.execution.market import ExecutionCommands134135 commands = ExecutionCommands(commit_decision, profile, binding['run_id'])136 capture = AgentToolCapture(137 pipeline.driver, partial(commands.commit, binding['maker_id']), pipeline.require_owner138 )139 tool_binding = dict(binding['config'], work_id='work-1', epoch='1')140 output = AgentPipelineOutput(141 recorder, lambda path: archive_log(profile, binding['run_id'], path)142 )143 trading = TradingTools(144 tool_binding, capture, capture.submit, capture.cancel, lambda: pipeline.receipt_index145 )146 queries = AgentTools(tool_binding, capture, lambda: pipeline.receipt_index, trading)147 from .agent_driver import PreparedToolCapture148149 queries.bind_market_capture(150 PreparedToolCapture(151 pipeline.reader,152 pipeline.driver.execution.snapshot,153 load_run_fundamentals(154 binding['config'], pipeline.reader, binding['config']['symbol']155 ),156 load_run_documents(binding['config']),157 )158 )159 pipeline.bind_market_reads(queries.market_read)160 from .binding import RuntimeBinding161162 controls = RuntimeBinding(runtime, pipeline, queries.binding, capture)163 queries.controls = controls164 pipeline.bind_lifecycle(controls)165 pipeline.bind_ready(166 operation=queries.dispatch, sink=output, cancel_queries=queries.cancel_pending167 )168 return queries, recorder169 except Exception as exc:170 cleanup_after_error(exc, *((queries.close,) if queries is not None else ()), recorder.close)171 raise172173174def bind_agent_host(175 runner: AgentDecisionRunner,176 tools: AgentTools,177 runtime: ExperimentRuntimeHandle,178 config: Dict[str, Any],179 agent_factory: Optional[AgentFactory] = None,180 launch: Optional[AgentLaunch] = None,181) -> None:182 """Bind program and participant gates; rollback the child if binding fails."""183 from sim_platform.agents.hosting.host import AgentProcessHost184 from sim_platform.agents.hosting.protocol import TransportLimits185186 program_config = dict(187 run_id=runner.run_id, work_id='work-1', epoch='1', symbol=config['symbol']188 )189 integration = config['definition']['integration']190 if launch is not None:191 from sim_platform.agents.hosting.loader import ProjectFactory192193 agent_factory = ProjectFactory(launch['project'])194 if integration != 'configured' and agent_factory is None:195 raise ContractError('custom Agent requires saved source or an explicit trusted factory')196 program_config['integration'] = integration197 program_config['template'] = dict(198 initial_prompt=config['definition']['initial_prompt'],199 parameters=config['definition']['parameters'],200 granted_tools=config['granted_tools'],201 limits=config['limits'],202 symbol=config['symbol'],203 # Present only for a run on several symbols, so one-symbol settings are unchanged.204 **({'symbols': list(config['symbols'])} if config.get('symbols') else {}),205 )206 host = AgentProcessHost(207 runner.request_tool,208 program_config,209 TransportLimits.from_configuration(config['limits']),210 request_work=runner.next_work,211 on_exit=runner.agent_exited,212 work_client=runtime.work_client(),213 local_model=True,214 agent_factory=agent_factory,215 launch=launch,216 )217 try:218 runner.bind_process(host)219 from sim_platform.experiments.execution.controls import ExperimentControls220221 runner.bind_barrier(222 ExperimentControls(223 runner.pipeline,224 runtime,225 decision=host,226 tools=tools,227 record=lambda value: tools.controls.record_notice('control_ack', value),228 )229 )230 except Exception as exc:231 cleanup_after_error(exc, host.close)232 raise233234235def assemble_agent_runner(236 profile: str,237 binding: AgentBinding,238 market: PreparedSession,239 log_path: Optional[Union[str, PathLike[str]]],240 clock: Optional[SharedExperimentClock] = None,241 *,242 services: AgentAssemblyServices,243 agent_factory: Optional[AgentFactory] = None,244) -> AgentDecisionRunner:245 """Create owned children for one runner; never register children as roots."""246 from decimal import Decimal247 from sim_platform.decisions.agent.runner import AgentDecisionRunner248249 pipeline = runner = None250 tools = recorder = runtime = launch = None251 try:252 config = binding['config']253 launch = (254 services.resolve_project(profile, config['definition'])255 if config['definition'].get('package') and agent_factory is None256 else None257 )258 if config.get('sandbox') is not None:259 from sim_platform.agents.hosting.processes.sandbox import resolve, validate260261 chosen = validate(config['sandbox'])262 if chosen is not None:263 if launch is None:264 raise ContractError('a sandbox runs an imported Agent project only')265 launch['sandbox'] = resolve(chosen)266 from sim_platform.experiments.scheduling.clock import SharedExperimentClock, session_gaps267 from dataclasses import asdict268 import multiprocessing269270 # speed 'turn': turn-based, the market waits while the Agent works.271 paced = config.get('speed') == 'turn'272 if clock is None:273 clock = SharedExperimentClock(274 multiprocessing.get_context('spawn'),275 int(config['start_ns']),276 session_gaps(277 market.reader.manifest, int(config['start_ns']), config.get('timeout_seconds')278 ),279 **({'paced': True} if paced else {}),280 )281 elif not isinstance(clock, SharedExperimentClock):282 raise ContractError('Agent runtime requires shared experiment clock')283 elif getattr(clock, 'paced', False) != paced:284 raise ContractError('a turn-based Agent needs a turn-based experiment clock')285 runtime = services.runtime_factory(286 config,287 clock=clock,288 prepared_artifact=market.reader.directory,289 prepared_news=[asdict(n) for n in getattr(market.reader, 'news', ())],290 )291 pipeline = create_agent_pipeline(292 services.execution_factory,293 services.compose_pipeline,294 profile,295 binding['run_id'],296 binding['maker_id'],297 market,298 start_ns=int(config['start_ns']),299 end_ns=int(config['end_ns']),300 lag_limit_ns=int(Decimal(config['lag']['threshold_seconds']) * NS_PER_SECOND),301 clock=clock,302 capacity=config['limits']['pending_requests'],303 lag_window_ns=int(Decimal(config['lag']['window_seconds']) * NS_PER_SECOND),304 )305 tools, recorder = bind_agent_tools(306 services.directory,307 services.create_log,308 services.archive_log,309 services.commit_decision,310 profile,311 binding['experiment_id'],312 binding,313 pipeline,314 log_path,315 runtime,316 )317 runner = AgentDecisionRunner(318 pipeline, tools, binding['run_id'], binding['experiment_id'], recorder319 )320 if paced:321 from .pacer import TurnPacer322 from sim_platform.experiments.scheduling.policy.schedule import seconds_ns323324 controls = tools.controls325 runner.bind_pacer(326 TurnPacer(327 clock,328 pipeline,329 runtime.snapshot,330 lambda: controls.published_sequence,331 seconds_ns(config['timeout_seconds']),332 )333 )334 from .presentation import AgentPresentation335336 runner.bind_presentation(337 AgentPresentation(services.presentation_operations, profile, binding, pipeline)338 )339 bind_agent_host(runner, tools, runtime, config, agent_factory, launch)340 return runner341 except Exception as exc:342 actions = (343 (runner.close,)344 if runner is not None345 else tuple(346 resource.close347 for resource in (pipeline, tools, recorder, runtime)348 if resource is not None349 )350 )351 if launch is not None and (runner is None or runner.process_host is None):352 actions += (launch['workspace'].close,)353 cleanup_after_error(354 exc, *actions, lambda: services.failed_start(profile, binding['run_id'])355 )356 raise