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

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    )