headless.py
1"""Run a whole experiment from one configuration, without the Desktop.23The command line (``market-lab experiment --config run.json``) and scripts use this to4do what the Desktop's New experiment form does: create an account, open the5experiment, configure the model, play it to the end and report the result with its6lineage check. A configuration is plain JSON:78.. code-block:: json910 {11 "profile_name": "Research",12 "cash_usd": 100000,13 "source": "/data/aapl.csv",14 "method": "agent",15 "execution_mode": "live",16 "agent_id": "my-agent", "revision": 1,17 "settings": {"symbol": "AAPL", "speed": "turn", "budget": {"max_tokens": 200000}},18 "execution": {"fee_per_share": 5, "latency_ns": 1000000},19 "model": {"provider": "openai-compatible", "model": "qwen2.5:7b",20 "base_url": "http://127.0.0.1:11434/v1"}21 }2223Fields: ``profile`` (an ID) or ``profile_name`` (found or created); ``cash_usd`` or24``cash`` (money units); ``source`` (path or list); ``method`` ('rule', 'model' or25'agent'); ``execution_mode`` ('controlled' or 'live'); ``settings``; ``execution``26(ExecutionConfig fields) or ``execution_preset`` ('paper' or 'strict'); ``allow_short``;27``book``; for Agents ``agent_id``, ``revision``, ``model`` (ModelProfile fields) and28``credential`` (``{"reference", "file", "variable"}`` to load a key from a .env file,29or ``{"reference", "environment"}`` to read it from an environment variable), and30``rehearsal`` (a symbol: answer with RehearsalProvider, no model calls);31``timeout_seconds`` bounds the wait (default one day).32"""3334from __future__ import annotations3536import os37import time38from typing import Any, Dict, Mapping, Optional3940from sim_platform.domain.models import ContractError4142# Money units per US dollar (prices and cash are integers in ten-thousandths).43UNITS_PER_USD = 10_00044# How often a Live or Agent experiment is serviced while it plays.45POLL_SECONDS = 0.0246# Default bound on one experiment's wait, in seconds.47DEFAULT_TIMEOUT_SECONDS = 86_40048FIELDS = frozenset(49 (50 'profile',51 'profile_name',52 'cash',53 'cash_usd',54 'account_name',55 'source',56 'method',57 'execution_mode',58 'settings',59 'execution',60 'execution_preset',61 'allow_short',62 'book',63 'agent_id',64 'revision',65 'model',66 'credential',67 'rehearsal',68 'timeout_seconds',69 )70)717273def _profile(platform: Any, config: Mapping[str, Any]) -> str:74 if config.get('profile'):75 return str(config['profile'])76 name = config.get('profile_name') or 'Research'77 for profile in platform.profiles():78 if profile['name'] == name:79 return str(profile['id'])80 return str(platform.create_profile(name))818283def _execution(config: Mapping[str, Any]) -> Any:84 from sim_platform.execution import ExecutionConfig8586 if config.get('execution_preset'):87 if config.get('execution'):88 raise ContractError('give execution or execution_preset, not both')89 from sim_platform.reference_agents import execution_preset9091 return execution_preset(config['execution_preset'])92 return ExecutionConfig(**(config.get('execution') or {}))939495def _credential(platform: Any, config: Mapping[str, Any]) -> None:96 credential = config.get('credential')97 if not credential:98 return99 reference = credential.get('reference')100 if credential.get('file'):101 platform.load_model_credential(102 reference, credential['file'], variable=credential.get('variable', 'OPENAI_API_KEY')103 )104 elif credential.get('environment'):105 secret = os.environ.get(credential['environment'])106 if not secret:107 raise ContractError(f'environment variable {credential["environment"]} is not set')108 platform.set_model_credential(reference, secret)109 else:110 raise ContractError('credential needs a file or an environment variable')111112113def _wait(experiment: Any, timeout: float, agent: bool, controlled: bool) -> None:114 """Play or step the experiment until it ends (and an Agent's log is archived)."""115 deadline = time.monotonic() + timeout116 if controlled and not agent:117 while experiment.runner.active:118 experiment.step()119 if time.monotonic() > deadline:120 experiment.stop()121 raise ContractError('experiment did not finish before its timeout')122 return123 experiment.play()124 while experiment.runner.active or (agent and not experiment.runner.archive_ready):125 experiment.tick(render=False)126 time.sleep(POLL_SECONDS)127 if time.monotonic() > deadline:128 experiment.stop()129 raise ContractError('experiment did not finish before its timeout')130 experiment.tick(render=False)131132133def run_experiment(platform: Any, config: Mapping[str, Any]) -> Dict[str, Any]:134 """Create an account, run one experiment to its end and report it.135136 Returns ``{'profile', 'account', 'run_id', 'status', 'summary', 'verified'}`` where137 ``verified`` is the run's lineage check (``Platform.verify_run``).138 """139 unknown = set(config) - FIELDS140 if unknown:141 raise ContractError('unknown experiment fields: ' + ', '.join(sorted(unknown)))142 if 'source' not in config or 'method' not in config:143 raise ContractError('an experiment needs source and method')144 method = config['method']145 agent = method == 'agent'146 profile = _profile(platform, config)147 cash = (148 int(round(float(config['cash_usd']) * UNITS_PER_USD))149 if 'cash_usd' in config150 else int(config.get('cash', 100_000 * UNITS_PER_USD))151 )152 account = platform.create_account(profile, config.get('account_name', 'Experiment'), cash)153 options: Dict[str, Any] = dict(154 source=config['source'],155 method=method,156 settings=config.get('settings'),157 execution_config=_execution(config),158 execution_mode=config.get('execution_mode', 'live' if agent else 'controlled'),159 )160 if agent:161 options.update(agent_id=config['agent_id'], revision=int(config['revision']))162 else:163 options.update(allow_short=bool(config.get('allow_short', False)), book=config.get('book'))164 experiment = platform.open_experiment(profile, account, **options)165 try:166 if agent:167 from sim_platform.models.contracts import ModelProfile168169 _credential(platform, config)170 provider: Optional[Any] = None171 if config.get('rehearsal'):172 from sim_platform.models.providers.rehearsal import RehearsalProvider173174 provider = RehearsalProvider(str(config['rehearsal']))175 platform.configure_experiment_model(176 experiment, ModelProfile(**(config.get('model') or {})), provider=provider177 )178 _wait(179 experiment,180 float(config.get('timeout_seconds', DEFAULT_TIMEOUT_SECONDS)),181 agent,182 options['execution_mode'] == 'controlled',183 )184 report = experiment.report()185 run_id = experiment.run_id186 finally:187 experiment.close()188 proof = platform.verify_run(profile, run_id)189 return dict(190 profile=profile,191 account=account,192 run_id=run_id,193 status=report['run']['status'],194 summary=report['summary'],195 verified=dict(unchanged=proof['unchanged'], sealed=proof['sealed']),196 )