research.py
1"""Batch evaluation and independent policy comparison commands."""23from __future__ import annotations45from typing import TYPE_CHECKING, Any, Callable, Dict, Optional67import argparse8import json9from pathlib import Path10from tempfile import TemporaryDirectory1112from ..context import CliContext13from ..output import emit_json14from ..arguments import money15from sim_platform.domain.models import ContractError1617if TYPE_CHECKING: # Annotation only.18 from ..arguments import Subcommands192021# Defaults for evaluation and comparison runs.22DEFAULT_CASH = 100_000_000 # money units23DEFAULT_FEE_PER_SHARE = 100 # money units24DEFAULT_QUANTITY = 1025DEFAULT_HOLD_NS = 2_000_000_000262728def register(commands: Subcommands) -> None:29 evaluation = commands.add_parser(30 'evaluate', help='batch rule evaluation through the shared core'31 )32 comparison = commands.add_parser('compare', help='independent equal-start rule comparisons')33 for command in (evaluation, comparison):34 command.add_argument('--input', type=Path, required=True)35 command.add_argument('--news', type=Path)36 command.add_argument('--symbol', default='AAPL')37 command.add_argument('--library', type=Path)38 command.add_argument('--allow-implicit-eof', action='store_true')39 command.add_argument('--cash', type=money, default=DEFAULT_CASH)40 command.add_argument('--fee-per-share', type=money, default=DEFAULT_FEE_PER_SHARE)41 command.add_argument('--latency-ns', type=int, default=0)42 command.add_argument('--output', type=Path)43 command.add_argument(44 '--bar-spread',45 type=money,46 help='price-bar .csv only: synthetic best ask minus best bid in USD; 0.02',47 )48 command.add_argument(49 '--book-depth', type=int, help='price-bar .csv only: synthetic levels per side; 5'50 )51 command.add_argument(52 '--allow-short',53 action='store_true',54 help='allow short selling under the documented margin rule',55 )56 evaluation.add_argument('--policy', choices=('rule', 'hold', 'model'), default='rule')57 evaluation.add_argument('--quantity', type=int, default=DEFAULT_QUANTITY)58 evaluation.add_argument('--hold-ns', type=int, default=DEFAULT_HOLD_NS)59 evaluation.add_argument(60 '--model-file', type=Path, help='with --policy model: your Python file defining decide()'61 )62 evaluation.add_argument(63 '--model-parameters', type=json.loads, default={}, help='JSON object passed to the model'64 )65 evaluation.add_argument('--lookback-bars', type=int, default=50)66 evaluation.add_argument(67 '--model-python', type=Path, help='interpreter for the model; default: this Python'68 )69 evaluation.add_argument('--model-timeout', type=float, default=10, help='seconds per call')70 comparison.add_argument(71 '--summary-only',72 action='store_true',73 help='persist independent runs and return compact summaries',74 )75 comparison.add_argument(76 '--configurations', type=Path, help='JSON list of named policy/quantity/hold_ns settings'77 )78 evaluation.set_defaults(handler=run_evaluation)79 comparison.set_defaults(handler=run_comparison)808182def _book(args: argparse.Namespace) -> Optional[Dict[str, int]]:83 """The synthetic-book choice for a price-bar input, or None for the defaults."""84 book = {}85 if args.bar_spread is not None:86 book['spread'] = args.bar_spread87 if args.book_depth is not None:88 book['depth'] = args.book_depth89 return book or None909192def _options(args: argparse.Namespace) -> Dict[str, Any]:93 return dict(94 book=_book(args),95 allow_short=args.allow_short,96 symbol=args.symbol,97 news=str(args.news) if args.news else None,98 library=str(args.library) if args.library else None,99 cash=args.cash,100 fee_per_share=args.fee_per_share,101 latency_ns=args.latency_ns,102 allow_implicit_eof=args.allow_implicit_eof,103 )104105106def _report(107 args: argparse.Namespace,108 result: Any,109 *,110 exporter: Optional[Callable[[Any, Any], Any]] = None,111) -> int:112 """Print (and optionally export) a report; exit code 1 if any run failed."""113 from sim_platform.research import export_report114115 if args.output:116 inputs = [args.input.resolve()]117 if args.news:118 inputs.append(args.news.resolve())119 if args.output.resolve() in inputs:120 raise ContractError("report destination cannot overwrite an input")121 (exporter or export_report)(result, args.output.resolve())122 emit_json(result)123 reports = [item['report'] for item in result['results']] if 'results' in result else [result]124 return 1 if any(report['summary']['status'] == 'failed' for report in reports) else 0125126127def run_evaluation(args: argparse.Namespace, context: CliContext) -> int:128 with context.open_platform() as platform:129 batch = platform.open_batch(library=args.library)130 model = None131 if args.policy == 'model':132 if args.model_file is None:133 raise ContractError('--policy model needs --model-file')134 model = dict(135 model_file=str(args.model_file.resolve()),136 model_parameters=args.model_parameters,137 lookback_bars=args.lookback_bars,138 model_python=str(args.model_python) if args.model_python else None,139 model_timeout_seconds=args.model_timeout,140 )141 result = batch.evaluate(142 args.input,143 policy=args.policy,144 quantity=args.quantity,145 hold_ns=args.hold_ns,146 model=model,147 **_options(args),148 )149 return _report(args, result, exporter=batch.export)150151152def run_comparison(args: argparse.Namespace, context: CliContext) -> int:153 context.resolve_directory() # Validate explicit/global directory even for temporary comparisons.154 configurations = json.loads(args.configurations.read_text()) if args.configurations else None155156 def run(selected: CliContext) -> int:157 with selected.open_platform() as platform:158 batch = platform.open_batch(library=args.library)159 result = batch.compare(160 str(args.input),161 configurations,162 include_details=not args.summary_only,163 **_options(args),164 )165 return _report(args, result, exporter=batch.export)166167 if args.summary_only or context.data_dir is not None:168 return run(context)169 with TemporaryDirectory(prefix='trading-comparison-') as temporary:170 context.select_directory(Path(temporary))171 try:172 return run(context)173 finally:174 context.close()