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

batch.py

1"""Independent equal-start comparisons through the same research controller."""23from __future__ import annotations45from pathlib import Path6from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, cast78from sim_platform.domain.models import ContractError9from sim_platform.domain.json_values import copy_json10from sim_platform.decisions.policy.contracts import make_policy11from sim_platform.decisions.policy.models import DEFAULT_HOLD_NS, DEFAULT_RULE_QUANTITY1213if TYPE_CHECKING:  # Annotation only.14    from sim_platform.decisions.policy.runner import PolicyDecisionRunner15    from sim_platform.market.native import PathInput16    from sim_platform.market.prepared.session import PreparedSession17    from .jobs import Cancellation18    from .controller import Preparation19    from .policy_controller import PolicyResearchController20    from .reports import ExportWriter, Report2122# Defaults for one batch evaluation.23DEFAULT_SYMBOL = 'AAPL'24DEFAULT_CASH = 100_000_000  # money-scale units25DEFAULT_FEE_PER_SHARE = 100  # money-scale units26# Evaluation progress is reported once every this many ticks.27PROGRESS_TICK_INTERVAL = 25628# A comparison runs between 1 and this many configurations.29MAX_COMPARISON_CONFIGURATIONS = 2030# Hold durations compared when the caller gives no configurations.31ONE_SECOND_NS = 1_000_000_0003233# Receives {'stage', 'frames', 'time_ns'} while a batch prepares or evaluates.34BatchProgress = Callable[[Dict[str, Any]], None]35# One comparison entry: optional 'name', 'policy', 'quantity' and 'hold_ns'.36ComparisonConfiguration = Dict[str, Any]37# Runs one evaluation: evaluator(path, cancellation=..., progress=..., include_details=..., **settings).38Evaluator = Callable[..., Optional['Report']]394041def _evaluate(42    controller_factory: Callable[[], PolicyResearchController],43    path: PathInput,44    *,45    symbol: str = DEFAULT_SYMBOL,46    news: Optional[PathInput] = None,47    policy: str = 'rule',48    quantity: int = DEFAULT_RULE_QUANTITY,49    hold_ns: int = DEFAULT_HOLD_NS,50    cash: int = DEFAULT_CASH,51    fee_per_share: int = DEFAULT_FEE_PER_SHARE,52    latency_ns: int = 0,53    library: Optional[PathInput] = None,54    allow_implicit_eof: bool = False,55    cancellation: Optional[Cancellation] = None,56    progress: Optional[BatchProgress] = None,57    include_details: bool = True,58    start_mode: str = 'beginning',59    start_time_ns: Optional[int] = None,60    model: Optional[Dict[str, Any]] = None,61    book: Optional[Dict[str, int]] = None,62    allow_short: bool = False,63    profile: Optional[str] = None,64    end_time_ns: Optional[int] = None,65) -> Optional[Report]:66    """Run one automatic policy on its own new account; None if cancelled during preparation.6768    ``profile`` puts that account in an existing profile, so the run can be evaluated69    with the profile's other runs (Platform.evaluation); by default a new profile is made.70    ``end_time_ns`` stops the run at the first market event at or after that time, as an71    Agent run stops at its chosen end; it is saved with the run's source.7273    ``model`` holds the model method's settings (configuration.MODEL_DEFAULTS keys) and74    is used only with policy='model'. ``book`` sets a price-bar recording's synthetic75    spread and depth (market.prepared.bars.book_options).76    """77    if policy == 'human':78        raise ContractError('batch evaluation requires a rule policy')79    if policy == 'model':80        from .configuration import MODEL_DEFAULTS, model_settings8182        if not isinstance(model, dict) or set(model) - set(MODEL_DEFAULTS):83            raise ContractError('the model policy needs model settings')84        model = model_settings(dict(MODEL_DEFAULTS, **model))85    else:86        make_policy(policy, quantity, hold_ns)87    controller = controller_factory()88    try:89        if profile is None:90            profile = controller.create_profile('Batch research')91        account = controller.create_account(profile, 'Independent account', cash)92        controller.begin_prepare(93            path, symbol, news, allow_implicit_eof, start_mode, start_time_ns, book=book94        )95        # begin_prepare set the preparation and the market it prepares.96        while cast('Preparation', controller.preparation)['status'] == 'preparing':97            if cancellation is not None and cancellation.cancelled:98                controller.cancel_preparation()99                return None100            controller.prepare_tick()101            if progress is not None:102                progress(103                    dict(104                        stage='preparation',105                        frames=cast('PreparedSession', controller.market).snapshot.sequence,106                        time_ns=cast('PreparedSession', controller.market).time_ns,107                    )108                )109        if end_time_ns is not None:110            # Saved with the run so evaluations can compare its market-time window.111            cast(Dict[str, Any], controller.source)['end_time_ns'] = int(end_time_ns)112        controller.start(113            profile,114            account,115            policy,116            quantity,117            hold_ns,118            fee_per_share,119            latency_ns,120            execution_mode='controlled',121            model=model,122            allow_short=allow_short,123        )124        controller.play()125        ticks = 0126        # start() bound a controlled-mode PolicyDecisionRunner.127        while cast('PolicyDecisionRunner', controller.runner).snapshot.status == 'running':128            if cancellation is not None and cancellation.cancelled:129                controller.stop()130                break131            if (132                end_time_ns is not None133                and cast('PreparedSession', controller.market).time_ns >= end_time_ns134            ):135                controller.stop()136                break137            controller.tick(render=False)138            ticks += 1139            if progress is not None and ticks % PROGRESS_TICK_INTERVAL == 0:140                progress(141                    dict(142                        stage='evaluation',143                        frames=cast('PreparedSession', controller.market).snapshot.sequence,144                        time_ns=cast('PreparedSession', controller.market).time_ns,145                    )146                )147        if include_details:148            return controller.report()149        from .reports import report_view150151        report = report_view(controller.app, profile, cast(str, controller.run_id))152        return dict(153            format=report['format'],154            run={'id': controller.run_id, 'profile_id': profile},155            source=report['source'],156            summary=report['summary'],157        )158    finally:159        controller.close()160161162# How often an Agent evaluation checks whether its run has ended (seconds).163AGENT_POLL_SECONDS = 0.05164# A suite entry's Agent model: ModelProfile fields.165MODEL_FIELDS = {166    'provider',167    'model',168    'credential_ref',169    'network_timeout_seconds',170    'max_output_tokens',171    'temperature',172    'base_url',173}174175176def _evaluate_agent(177    platform: Any,178    path: PathInput,179    *,180    profile: str,181    agent_id: str,182    revision: int,183    settings: Dict[str, Any],184    model: Dict[str, Any],185    symbol: str = DEFAULT_SYMBOL,186    cash: int = DEFAULT_CASH,187    fee_per_share: int = DEFAULT_FEE_PER_SHARE,188    latency_ns: int = 0,189    model_provider: Optional[Callable[[], Any]] = None,190    cancellation: Optional[Cancellation] = None,191    progress: Optional[BatchProgress] = None,192    include_details: bool = True,193    preparation_lock: Optional[Any] = None,194    **_: Any,195) -> Optional[Report]:196    """Run a saved Agent revision once, in real time, on its own new account.197198    The Agent trades from settings['start_ns'] to settings['end_ns'] at 1x: market time199    passes as wall-clock time passes, so a run takes as long as its window. ``model``200    holds ModelProfile fields; its credential must already be stored on the Platform.201    ``model_provider`` returns a fresh trusted provider per run (None: the default202    adapter). ``preparation_lock`` (a threading lock) makes concurrent runs prepare their203    market one at a time, since a workspace prepares one market at once; they then play204    together. Arguments meant for Rule and model-file runs are ignored. Returns the full205    report, or None if cancelled.206    """207    from contextlib import nullcontext208    import time209210    from sim_platform.execution import ExecutionConfig211    from sim_platform.models.contracts import ModelProfile212213    account = platform.create_account(profile, 'Independent account', cash)214    with preparation_lock if preparation_lock is not None else nullcontext():215        experiment = platform.open_experiment(216            profile,217            account,218            source=path,219            method='agent',220            agent_id=agent_id,221            revision=revision,222            settings=dict(settings, symbol=symbol),223            execution_config=ExecutionConfig(fee_per_share=fee_per_share, latency_ns=latency_ns),224            execution_mode='live',225        )226    try:227        platform.configure_experiment_model(228            experiment,229            ModelProfile(**model),230            provider=model_provider() if model_provider is not None else None,231        )232        experiment.play()233        while experiment.runner is not None and experiment.runner.active:234            if cancellation is not None and cancellation.cancelled:235                experiment.stop()236                return None237            experiment.tick(render=False)238            if progress is not None:239                progress(dict(stage='agent', frames=0, time_ns=experiment.market.time_ns))240            time.sleep(AGENT_POLL_SECONDS)241        # The market tail is saved only once the runner reports it ready; wait for it so242        # the report has its bars and closes.243        while experiment.runner is not None and not experiment.runner.archive_ready:244            experiment.tick(render=False)245            time.sleep(AGENT_POLL_SECONDS)246        experiment.tick(render=False)247        report = experiment.report()248        from .evaluation import agent_model_usage249250        report['model_usage'] = agent_model_usage(251            platform.agent_log_archive(profile, experiment.run_id)252        )253        if include_details:254            return report255        return dict(256            format=report['format'],257            run={'id': experiment.run_id, 'profile_id': profile},258            source=report['source'],259            summary=report['summary'],260        )261    finally:262        experiment.close()263264265def _compare(266    path: PathInput,267    configurations: Optional[List[ComparisonConfiguration]] = None,268    *,269    evaluator: Evaluator,270    cancellation: Optional[Cancellation] = None,271    progress: Optional[BatchProgress] = None,272    include_details: bool = True,273    **common: Any,274) -> Report:275    """Evaluate each configuration on its own account and collect a comparison report."""276    configurations = (277        [278            {'name': 'Hold 1 second', 'hold_ns': ONE_SECOND_NS},279            {'name': 'Hold 2 seconds', 'hold_ns': 2 * ONE_SECOND_NS},280        ]281        if configurations is None282        else configurations283    )284    if (285        not isinstance(configurations, list)286        or not 1 <= len(configurations) <= MAX_COMPARISON_CONFIGURATIONS287    ):288        raise ContractError('comparison requires 1..20 configurations')289    allowed = {'name', 'policy', 'quantity', 'hold_ns'}290    configurations = cast(List[ComparisonConfiguration], copy_json(configurations))291    for config in configurations:292        if not isinstance(config, dict) or set(config) - allowed:293            raise ContractError('invalid comparison configuration')294        if 'name' in config:295            from sim_platform.domain.models import label296297            label(config['name'], 'comparison name')298        policy = config.get('policy', common.get('policy', 'rule'))299        if policy == 'human':300            raise ContractError('batch evaluation requires a rule policy')301        make_policy(302            policy,303            config.get('quantity', common.get('quantity', DEFAULT_RULE_QUANTITY)),304            config.get('hold_ns', common.get('hold_ns', DEFAULT_HOLD_NS)),305        )306    results: List[Dict[str, Any]] = []307    for config in configurations:308        if cancellation is not None and cancellation.cancelled:309            break310        arguments = {**common, **{k: v for k, v in config.items() if k != 'name'}}311        report = evaluator(312            path,313            cancellation=cancellation,314            progress=progress,315            include_details=include_details,316            **arguments,317        )318        if report is None and cancellation is not None and cancellation.cancelled:319            break320        results.append(321            # report is None only after cancellation, which ends the loop above.322            dict(323                name=config.get('name', 'Rule'),324                summary=cast('Report', report)['summary'],325                report=report,326            )327        )328    settings = {329        k: str(v) if k in ('news', 'library') and v is not None else v for k, v in common.items()330    }331    return copy_json(332        dict(333            format='trading-comparison-v1',334            status=(335                'cancelled' if cancellation is not None and cancellation.cancelled else 'completed'336            ),337            pending_configurations=configurations[len(results) :],338            experiment='independent equal-start accounts; no handoff',339            common_settings=settings,340            configurations=configurations,341            results=results,342        )343    )344345346# One suite entry: 'name', 'policy' ('rule', 'model' or 'agent') and 'repetitions'. A347# rule entry may give 'quantity' and 'hold_ns'; a model entry gives 'model' (model-file348# settings); an Agent entry gives 'agent_id', 'revision', 'settings' (Agent experiment349# settings with 'start_ns' and 'end_ns') and 'model' (ModelProfile fields).350SuiteEntry = Dict[str, Any]351# Most recordings one suite evaluates.352MAX_SUITE_RECORDINGS = 20353# Most repetitions of one entry on one recording.354MAX_REPETITIONS = 200355# Repetitions of an Agent entry unless given: its model answers differently each run.356DEFAULT_AGENT_REPETITIONS = 10357# Most Agent runs a suite plays at the same time.358MAX_CONCURRENCY = 16359360361def _check_suite_entries(entries: List[SuiteEntry]) -> List[SuiteEntry]:362    from .evaluation import MAX_ENTRIES363364    if not isinstance(entries, list) or not 1 <= len(entries) <= MAX_ENTRIES:365        raise ContractError(f'a suite needs 1..{MAX_ENTRIES} entries')366    allowed = {'name', 'policy', 'quantity', 'hold_ns', 'model', 'repetitions'}367    agent_keys = {'name', 'policy', 'agent_id', 'revision', 'settings', 'model', 'repetitions'}368    entries = cast(List[SuiteEntry], copy_json(entries))369    names = set()370    for entry in entries:371        if not isinstance(entry, dict) or 'name' not in entry:372            raise ContractError('each suite entry is a dict with a name')373        policy = entry.get('policy', 'rule')374        if set(entry) - (agent_keys if policy == 'agent' else allowed):375            raise ContractError(f'entry {entry["name"]!r} has keys its policy does not use')376        if entry['name'] in names:377            raise ContractError(f'entry name {entry["name"]!r} is used twice')378        names.add(entry['name'])379        if policy == 'agent':380            entry.setdefault('repetitions', DEFAULT_AGENT_REPETITIONS)381            settings, model = entry.get('settings'), entry.get('model')382            if (383                not isinstance(entry.get('agent_id'), str)384                or not isinstance(entry.get('revision'), int)385                or not isinstance(settings, dict)386                or 'start_ns' not in settings387                or 'end_ns' not in settings388            ):389                raise ContractError(390                    'an Agent entry needs agent_id, revision and settings with start_ns and end_ns'391                )392            if not isinstance(model, dict) or set(model) - MODEL_FIELDS:393                raise ContractError('an Agent entry needs model: ModelProfile fields')394        elif policy not in ('rule', 'model'):395            raise ContractError('suite entries use the rule, model or agent policy')396        repetitions = entry.get('repetitions', 1)397        if (398            not isinstance(repetitions, int)399            or isinstance(repetitions, bool)400            or not 1 <= repetitions <= MAX_REPETITIONS401        ):402            raise ContractError(f'repetitions must be 1..{MAX_REPETITIONS}')403    return entries404405406def _evaluate_suite(407    paths: List[PathInput],408    entries: List[SuiteEntry],409    *,410    evaluator: Evaluator,411    agent_evaluator: Optional[Evaluator] = None,412    baseline: Optional[str] = None,413    metric: str = 'total_return',414    seed: int = 2026,415    resamples: int = 10_000,416    cancellation: Optional[Cancellation] = None,417    progress: Optional[BatchProgress] = None,418    model_provider: Optional[Callable[[], Any]] = None,419    training_cutoffs: Optional[Dict[str, str]] = None,420    concurrency: int = 1,421    token_prices: Optional[Dict[str, float]] = None,422    trials: Optional[Dict[str, int]] = None,423    **common: Any,424) -> Report:425    """Run every entry on every recording on new accounts, then evaluate each recording.426427    ``trials`` maps entry names to how many configurations were tried (for the deflated428    Sharpe ratio); sweeps pass their number of combinations.429430    With Agent entries, every entry trades the Agents' window: Rule and model-file runs431    start at its start_ns and stop at its end_ns, so all runs cover the same market time.432    ``concurrency`` plays up to that many runs of one Agent entry at the same time, each433    still in real time on its own account; it shortens the wait, not any run.434    """435    from functools import partial436    from pathlib import Path437    from threading import Lock438439    from .evaluation import evaluate_reports, memorisation_flags440441    if not isinstance(paths, list) or not 1 <= len(paths) <= MAX_SUITE_RECORDINGS:442        raise ContractError(f'a suite needs a list of 1..{MAX_SUITE_RECORDINGS} recordings')443    entries = _check_suite_entries(entries)444    if baseline is not None and baseline not in {e['name'] for e in entries}:445        raise ContractError(f'baseline {baseline!r} is not one of the entries')446    if (447        not isinstance(concurrency, int)448        or isinstance(concurrency, bool)449        or not 1 <= concurrency <= MAX_CONCURRENCY450    ):451        raise ContractError(f'concurrency must be 1..{MAX_CONCURRENCY}')452    cutoffs = training_cutoffs or {}453    if not isinstance(cutoffs, dict) or set(cutoffs) - {e['name'] for e in entries}:454        raise ContractError('training_cutoffs must map entry names to dates')455    agents = [e for e in entries if e.get('policy') == 'agent']456    window: Dict[str, Any] = {}457    if agents:458        if agent_evaluator is None:459            raise ContractError('this batch cannot run Agents; open it with Platform.open_batch()')460        if not common.get('profile'):461            raise ContractError('Agent entries need the profile that holds the saved Agents')462        windows = {(str(e['settings']['start_ns']), str(e['settings']['end_ns'])) for e in agents}463        if len(windows) != 1:464            raise ContractError('every Agent entry must use the same start_ns and end_ns')465        start, end = (int(v) for v in windows.pop())466        window = dict(start_mode='custom', start_time_ns=start, end_time_ns=end)467        # The Agent saves its source's resolved path; give every run the same one.468        paths = [str(Path(p).expanduser().resolve()) for p in paths]469    recordings: List[Dict[str, Any]] = []470    cancelled = False471    preparation_lock = Lock()472    for path in paths:473        reports: Dict[str, List[Report]] = {}474        for entry in entries:475            settings = {476                k: v for k, v in entry.items() if k not in ('name', 'repetitions', 'policy')477            }478            agent = entry.get('policy') == 'agent'479            repetitions = entry.get('repetitions', 1)480            if agent:481                run = partial(482                    cast(Evaluator, agent_evaluator),483                    path,484                    cancellation=cancellation,485                    progress=progress,486                    include_details=True,487                    model_provider=model_provider,488                    preparation_lock=preparation_lock,489                    **{**common, **settings},490                )491            else:492                run = partial(493                    evaluator,494                    path,495                    cancellation=cancellation,496                    progress=progress,497                    include_details=True,498                    **{**window, **common, 'policy': entry.get('policy', 'rule'), **settings},499                )500            # Rule and model-file runs are synchronous and quick; only Agents run together.501            runs = _run_repetitions(run, repetitions, concurrency if agent else 1, cancellation)502            finished = [report for report in runs if report is not None]503            if finished:504                reports.setdefault(entry['name'], []).extend(finished)505            if len(finished) < repetitions:506                cancelled = True507            if cancelled:508                break509        if cancelled:510            break511        recordings.append(512            dict(513                path=str(path),514                evaluation=evaluate_reports(515                    reports,516                    baseline=baseline,517                    metric=metric,518                    seed=seed,519                    resamples=resamples,520                    token_prices=token_prices,521                    trials=trials,522                    flags={523                        report['run']['id']: memorisation_flags(report, cutoffs.get(name))524                        for name, group in reports.items()525                        for report in group526                    },527                ),528            )529        )530    return copy_json(531        dict(532            format='agent-evaluation-suite-v1',533            status='cancelled' if cancelled else 'completed',534            entries=entries,535            common_settings={536                k: str(v) if k in ('news', 'library') and v is not None else v537                for k, v in common.items()538            },539            concurrency=concurrency,540            recordings=recordings,541        )542    )543544545def _run_repetitions(546    run: Callable[[], Optional[Report]],547    repetitions: int,548    concurrency: int,549    cancellation: Optional[Cancellation],550) -> List[Optional[Report]]:551    """Call ``run`` ``repetitions`` times, at most ``concurrency`` at once, in order.552553    A None result (cancelled) or a cancellation stops further runs from starting; runs554    already playing finish or stop through their own cancellation check. The first555    error is raised after every started run has ended.556    """557    if concurrency == 1:558        results: List[Optional[Report]] = []559        for _ in range(repetitions):560            if cancellation is not None and cancellation.cancelled:561                break562            report = run()563            results.append(report)564            if report is None:565                break566        return results567    from concurrent.futures import ThreadPoolExecutor568569    def guarded() -> Optional[Report]:570        if cancellation is not None and cancellation.cancelled:571            return None572        return run()573574    with ThreadPoolExecutor(max_workers=concurrency, thread_name_prefix='agent-run') as pool:575        futures = [pool.submit(guarded) for _ in range(repetitions)]576    return [future.result() for future in futures]577578579class ResearchBatch:580    """Batch workflows use platform-configured controller factories, without opening a Platform.581582    Platform.open_batch creates and registers it. Each evaluation opens and closes its583    own controller through ``controller_factory``; the batch itself owns nothing else.584    close() (or leaving a ``with`` block) marks it closed and runs the on_close callback.585    """586587    def __init__(588        self,589        controller_factory: Callable[[], PolicyResearchController],590        directory: Path,591        *,592        export_writer: ExportWriter,593        agent_evaluator: Optional[Evaluator] = None,594    ) -> None:595        self._controller_factory = controller_factory596        self._agent_evaluator = agent_evaluator597        self.directory = directory598        self._export_writer = export_writer599        self._closed = False600        self._on_close: Callable[[], None] = lambda: None601602    def on_close(self, callback: Callable[[], None]) -> None:603        self._on_close = callback604605    def close(self) -> None:606        self._closed = True607        self._on_close()608609    def __enter__(self) -> ResearchBatch:610        if self._closed:611            raise ContractError('research batch is closed')612        return self613614    def __exit__(self, *_: object) -> None:615        self.close()616617    def evaluate(self, path: PathInput, **arguments: Any) -> Optional[Report]:618        if self._closed:619            raise ContractError('research batch is closed')620        return _evaluate(self._controller_factory, path, **arguments)621622    def compare(623        self,624        path: PathInput,625        configurations: Optional[List[ComparisonConfiguration]] = None,626        **arguments: Any,627    ) -> Report:628        if self._closed:629            raise ContractError('research batch is closed')630        return _compare(path, configurations, evaluator=self.evaluate, **arguments)631632    def evaluate_suite(633        self, paths: List[PathInput], entries: List[SuiteEntry], **arguments: Any634    ) -> Report:635        """Run each entry ``repetitions`` times per recording and evaluate each recording.636637        Every run gets its own new account. Arguments not named here (symbol, cash,638        fee_per_share, profile, ...) apply to every run. Agent entries run in real time639        over their window and need ``profile``; ``model_provider`` optionally returns a640        trusted model provider for each Agent run. Returns an641        'agent-evaluation-suite-v1' report with one evaluation per recording; see642        docs/user-guide/evaluation.md.643        """644        if self._closed:645            raise ContractError('research batch is closed')646        return _evaluate_suite(647            paths,648            entries,649            evaluator=self.evaluate,650            agent_evaluator=self._agent_evaluator,651            **arguments,652        )653654    def evaluate_benchmark(655        self, folder: PathInput, entries: List[SuiteEntry], **arguments: Any656    ) -> Report:657        """Run entries against the fixed benchmark baselines on its synthetic regimes.658659        Writes the reproducible benchmark recordings into ``folder`` and evaluates every660        entry against buy and hold, a one-day rule and a moving-average model; see661        research.benchmark and docs/user-guide/evaluation.md#benchmark.662        """663        if self._closed:664            raise ContractError('research batch is closed')665        from .benchmark import evaluate_benchmark666667        return evaluate_benchmark(self, folder, entries, **arguments)668669    def export(self, report: Report, path: PathInput) -> str:670        if self._closed:671            raise ContractError('research batch is closed')672        from .reports import export_report673674        return export_report(report, path, writer=self._export_writer)675676677def _borrow_batch(platform: Any, library: Optional[PathInput]) -> ResearchBatch:678    """Open a batch on the caller's Platform (application package, typed later)."""679    from sim_platform import Platform680681    if not isinstance(platform, Platform):682        raise ContractError('batch entry requires an existing Platform; use Platform.open_batch()')683    return platform.open_batch(library=library)684685686def evaluate(platform: Any, path: PathInput, **arguments: Any) -> Optional[Report]:687    """Legacy name; caller supplies and owns the Platform."""688    library = arguments.pop('library', None)689    with _borrow_batch(platform, library) as batch:690        return batch.evaluate(path, **arguments)691692693def compare(694    platform: Any,695    path: PathInput,696    configurations: Optional[List[ComparisonConfiguration]] = None,697    **arguments: Any,698) -> Report:699    """Legacy name; independent runs share the caller's Platform."""700    library = arguments.pop('library', None)701    with _borrow_batch(platform, library) as batch:702        return batch.compare(path, configurations, **arguments)