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

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)