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)