reports.py
1"""Consistent historical run reports and atomic JSON/CSV exports, without Qt."""23from __future__ import annotations45import csv6import json7from pathlib import Path8from typing import IO, TYPE_CHECKING, Any, Callable, Dict, Iterable, Optional910from sim_platform.domain.json_values import copy_json11from sim_platform.domain.models import ContractError, MONEY_SCALE1213if TYPE_CHECKING: # Annotation only.14 from sim_platform.market.native import PathInput1516# Report data read from the database: 'run', 'run_events', 'account_ledger', 'final'17# and optionally 'last_market', 'decision_tail', 'fill_count', 'decision_count'.18ReportData = Dict[str, Any]19# A 'trading-research-v1' report (see format_report) or a 'trading-comparison-v1'20# comparison with 'results'; values may be StreamArray while exporting.21Report = Dict[str, Any]22# Writes one file atomically: writer(path, serialize) calls serialize(stream) and23# returns the written path as text.24ExportWriter = Callable[[Path, Callable[[IO[str]], None]], str]252627def run_report(app: Any, profile: str, run_id: str) -> Report:28 """Build the full report for a run; ``app`` is application's DatabaseOperations."""29 data = app.report_data(profile, run_id)30 return format_report(data)313233def report_view(app: Any, profile: str, run_id: str) -> Report:34 """Build the bounded report used for display; ``app`` is DatabaseOperations."""35 return format_report(app.report_view_data(profile, run_id))363738def format_report(data: ReportData) -> Report:39 """Turn stored run data into a detached report with a summary and assumptions."""40 run, own, prefix, final = (data[k] for k in ('run', 'run_events', 'account_ledger', 'final'))41 ticks = [e for e in own if e['kind'] == 'execution_tick']42 market = data.get('last_market', ticks[-1]['data']['market'] if ticks else None)43 journal = run['policy_state']44 fills = [e for e in own if e['kind'] == 'fill']45 mark = market['bids'][0][0] if market and market['bids'] else None46 equity = (47 final['cash'] + sum(p['quantity'] * mark for p in final['positions'])48 if (mark is not None and all(p['symbol'] == market['symbol'] for p in final['positions']))49 else (final['cash'] if not final['positions'] else None)50 )51 return copy_json(52 dict(53 format='trading-research-v1',54 money_scale=MONEY_SCALE,55 currency='USD',56 run=run,57 initial=run['initial_snapshot'],58 final=final,59 market=market,60 source=run['config'].get('research_source'),61 account_ledger=prefix,62 run_events=own,63 decisions=data.get('decision_tail', journal.get('records', [])),64 handoffs=journal.get('handoffs', []),65 authority_rejections=journal.get('authority_rejections', []),66 market_data=journal.get('research_archive', {}),67 summary=dict(68 status=run['status'],69 cash=final['cash'],70 realized_pnl=final['realized_pnl'],71 fees=final['fees'],72 run_realized_pnl=final['realized_pnl'] - run['initial_snapshot']['realized_pnl'],73 run_fees=final['fees'] - run['initial_snapshot']['fees'],74 position_quantity=sum(p['quantity'] for p in final['positions']),75 fill_count=data.get('fill_count', len(fills)),76 decision_count=data.get('decision_count', len(journal.get('records', []))),77 handoff_count=len(journal.get('handoffs', [])),78 estimated_equity_at_bid=equity,79 valuation='last observed best bid; not guaranteed liquidation',80 ),81 assumptions=[82 'displayed-limit-v1 simulated execution',83 'no passive queue or broker',84 'historical account ledger prefix',85 'equity is an estimate; report is not a performance guarantee',86 ],87 )88 )899091class StreamArray:92 """Marks a large list that write_json streams item by item instead of copying.9394 Created by export_run for one export; it only wraps the iterable it was given.95 """9697 def __init__(self, values: Iterable[Any]) -> None:98 self.values = values99100101def write_json(stream: IO[str], value: Any) -> None:102 """Write a JSON value to ``stream``, streaming any StreamArray contents."""103 if isinstance(value, dict):104 stream.write('{')105 for index, (key, item) in enumerate(value.items()):106 if index:107 stream.write(',')108 stream.write(json.dumps(key, ensure_ascii=False) + ':')109 write_json(stream, item)110 stream.write('}')111 elif isinstance(value, (list, tuple, StreamArray)):112 stream.write('[')113 values = value.values if isinstance(value, StreamArray) else value114 for index, item in enumerate(values):115 if index:116 stream.write(',')117 write_json(stream, item)118 stream.write(']')119 else:120 stream.write(json.dumps(value, ensure_ascii=False, allow_nan=False))121122123def export_run(124 app: Any,125 profile: str,126 run_id: str,127 path: PathInput,128 *,129 writer: Optional[ExportWriter] = None,130) -> str:131 """Export a run's report while streaming its large record lists from the database."""132 with app.report_stream(profile, run_id) as (data, arrays):133 report = format_report(data)134 journal = report['run']['policy_state']135 if '_record_count' in journal:136 journal.pop('_record_count')137 journal['records'] = StreamArray(arrays.pop('nested_decisions'))138 for key, values in arrays.items():139 if key != 'nested_decisions':140 report[key] = StreamArray(values)141 return export_report(report, path, writer=writer)142143144def export_report(report: Report, path: PathInput, *, writer: Optional[ExportWriter] = None) -> str:145 """Write a report as JSON (or its run events as CSV) without overwriting an input file."""146 path = Path(path)147 if not path.is_absolute():148 raise ContractError('report destination must be absolute')149 sources = [report.get('source')] + [150 r.get('report', {}).get('source') for r in report.get('results', [])151 ]152 for source in sources:153 if source and any(154 Path(source[key]).resolve() == path.resolve()155 for key in ('path', 'news_path')156 if source.get(key)157 ):158 raise ContractError('report destination cannot overwrite an input')159 if path.suffix.lower() not in ('.json', '.csv'):160 raise ContractError('report extension must be .json or .csv')161 if path.suffix.lower() == '.csv' and 'run_events' not in report:162 raise ContractError('comparison export requires .json')163164 def serialize(stream: IO[str]) -> None:165 if path.suffix.lower() == '.json':166 write_json(stream, report)167 stream.write('\n')168 else:169 output = csv.writer(stream)170 output.writerow(['sequence', 'simulation_time_ns', 'kind', 'data_json', 'money_scale'])171 events = report['run_events']172 for event in events.values if isinstance(events, StreamArray) else events:173 output.writerow(174 [175 event['sequence'],176 event['time_ns'],177 event['kind'],178 json.dumps(179 event['data'], ensure_ascii=False, sort_keys=True, allow_nan=False180 ),181 MONEY_SCALE,182 ]183 )184185 if writer is None:186 # Legacy standalone export API uses the same persistence adapter.187 from sim_platform.persistence.export_files import atomic_write188189 writer = atomic_write190 return writer(path, serialize)