backtest-doctor 0.4.0__py3-none-any.whl

backtest_doctor/__init__.py

@@ -0,0 +1,2 @@
+"""Backtest Doctor: offline audits of synthetic or user-provided CSV reports."""
+__version__ = "0.4.0"

backtest_doctor/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

backtest_doctor/adapters.py

@@ -0,0 +1,71 @@
+"""Offline, bounded CSV adapters for *reported* settled trade returns.
+
+These adapters cannot reconstruct signal timing from trade-summary exports.
+No source code, pickle, native archives, account IDs, or proprietary data is read.
+"""
+from __future__ import annotations
+
+import math
+from .audit import _time, audit_stability
+
+# All return columns are fractional returns, not percent points.
+# backtesting.py ReturnPct / vectorbt Return / Freqtrade profit_ratio.
+FORMATS = frozenset(('backtesting-py', 'vectorbt', 'freqtrade-csv'))
+REQUIRED = {
+    'backtesting-py': ('ExitTime', 'ReturnPct'),
+    'vectorbt': ('Exit Timestamp', 'Return', 'Status'),
+    'freqtrade-csv': ('close_date', 'profit_ratio', 'is_open'),
+}
+
+
+def audit_imported_trades(rows, framework: str, additional_cost_bps: float = 0):
+    """Audit a CSV of already settled trades without copying identity columns.
+
+    - Reported trade return may already incorporate fees and slippage.
+    - Additional cost scenarios are *extra stress*, not actual fee estimates.
+    - Missing/naive timestamps, open trades, and non-finite returns fail closed.
+    """
+    if framework not in FORMATS:
+        raise ValueError('unsupported framework format')
+    if type(additional_cost_bps) not in (int, float) or not math.isfinite(additional_cost_bps) or additional_cost_bps < 0:
+        raise ValueError('additional cost must be finite and nonnegative')
+    if additional_cost_bps > 10_000:
+        raise ValueError('additional cost exceeds 100 percent')
+    if not rows:
+        raise ValueError('empty import')
+
+    ts_key, ret_key = REQUIRED[framework][:2]
+    mapped = []
+    for row in rows:
+        if any(key not in row or row[key] is None or not str(row[key]).strip() for key in REQUIRED[framework]):
+            raise ValueError('missing required framework field')
+        # Do not silently convert timezone-naive pandas timestamps to UTC.
+        timestamp = _time(row[ts_key])
+        try:
+            result = float(row[ret_key])
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise ValueError('invalid reported trade return') from exc
+        if not math.isfinite(result) or result <= -1:
+            raise ValueError('nonfinite or impossible reported return')
+        if framework == 'vectorbt' and row['Status'].strip().casefold() != 'closed':
+            raise ValueError('unsettled vectorbt trade not supported')
+        if framework == 'freqtrade-csv' and 'is_open' in row:
+            state = row['is_open'].strip().casefold()
+            if state not in ('false', '0', 'no'):
+                raise ValueError('freqtrade open or unknown trade state')
+        mapped.append({'exit_time': timestamp.isoformat(), 'gross_return': str(result)})
+
+    scenarios = (0,) if additional_cost_bps == 0 else (0, additional_cost_bps)
+    report = audit_stability(mapped, costs=scenarios)
+    # The inherited audit API calls its input gross_return, but native exports
+    # may *already* be net-of-fees. Never claim a reconstructed gross return.
+    report['audit_type'] = 'framework-trades'
+    report['metrics']['framework_format'] = framework
+    report['metrics']['reported_return_basis'] = 'framework-provided trade return; fee inclusion not independently verified'
+    report['metrics']['cost_scenario_interpretation'] = '0bps = unmodified reported return; positive bps = additional hypothetical per-trade drag'
+    report['metrics']['signal_timing_verified'] = False
+    report['findings'].append({'code': 'SIGNAL_CAUSALITY_NOT_VERIFIED', 'row': None, 'severity': 'WARNING'})
+    report['warnings'] += 1
+    if report['status'] != 'FAIL':
+        report['status'] = 'WARN'
+    return report

backtest_doctor/audit.py

@@ -0,0 +1,235 @@
+"""Offline CSV diagnostics; accepts no executable strategy code.
+
+Reports intentionally contain finding *codes* and row numbers, never input values,
+file paths, credentials, symbols, or strategy-level identifiers.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import math
+import os
+import stat
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+MAX_FILE_BYTES = 10 * 1024 * 1024
+MAX_ROWS = 100_000
+MAX_COLUMNS = 64
+MAX_FIELD_BYTES = 131_072
+MAX_FINDINGS = 2_000
+
+
+def _time(value):
+    value = str(value).strip()
+    if value.endswith('Z'):
+        value = value[:-1] + '+00:00'
+    stamp = datetime.fromisoformat(value)
+    if stamp.utcoffset() is None:
+        raise ValueError('timezone required')
+    return stamp.astimezone(timezone.utc)
+
+
+def _num(value):
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError('non-finite number')
+    return number
+
+
+def _finding(code, row=None, severity='ERROR'):
+    return {'code': code, 'row': row, 'severity': severity}
+
+
+def _push(findings, code, row=None, severity='ERROR'):
+    if len(findings) < MAX_FINDINGS:
+        findings.append(_finding(code, row, severity))
+    elif len(findings) == MAX_FINDINGS:
+        findings.append(_finding('FINDING_LIMIT_REACHED', severity='ERROR'))
+
+
+def _base(kind, findings, count, extras=None):
+    errors = sum(f['severity'] == 'ERROR' for f in findings)
+    warnings = sum(f['severity'] == 'WARNING' for f in findings)
+    return {
+        'report_schema_version': '0.4',
+        'audit_type': kind,
+        'status': 'FAIL' if errors else ('WARN' if warnings else 'PASS'),
+        'errors': errors,
+        'warnings': warnings,
+        'rows_examined': count,
+        'findings': findings,
+        'metrics': extras or {},
+        'data_policy': 'aggregate-only; no raw inputs included',
+    }
+
+
+def read_csv(path):
+    """Read at most 10 MiB from a regular file, with no symlink following.
+
+    The byte cap is enforced even if the file grows after the initial stat.
+    This is not a general sandbox against hostile mounts or filesystem races.
+    """
+    path = Path(path)
+    if path.is_symlink():
+        raise ValueError('symlink input is prohibited')
+    flags = os.O_RDONLY
+    if hasattr(os, 'O_NOFOLLOW'):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(path, flags)
+    with os.fdopen(fd, 'rb') as handle:
+        st = os.fstat(handle.fileno())
+        if not stat.S_ISREG(st.st_mode) or st.st_size > MAX_FILE_BYTES:
+            raise ValueError('input is not a regular file or is too large')
+        raw = handle.read(MAX_FILE_BYTES + 1)
+        if len(raw) > MAX_FILE_BYTES:
+            raise ValueError('input exceeds file size limit')
+    content = raw.decode('utf-8-sig')
+    csv.field_size_limit(MAX_FIELD_BYTES)
+    reader = csv.DictReader(io.StringIO(content, newline=''), strict=True)
+    headers = reader.fieldnames
+    if (not headers or len(headers) > MAX_COLUMNS or any(not h for h in headers)
+            or len(set(headers)) != len(headers)):
+        raise ValueError('invalid or duplicate CSV columns')
+    rows = []
+    for i, row in enumerate(reader, start=1):
+        if i > MAX_ROWS:
+            raise ValueError('input exceeds row safety limit')
+        if None in row or any(v is None for v in row.values()):
+            raise ValueError('malformed CSV row')
+        rows.append(row)
+    return rows
+
+
+def audit_ohlcv(rows, interval_seconds=None):
+    findings, seen, prior = [], set(), None
+    required = ('timestamp', 'open', 'high', 'low', 'close', 'volume')
+    if interval_seconds is not None and (type(interval_seconds) is not int or interval_seconds <= 0):
+        raise ValueError('interval must be positive integer')
+    if not rows:
+        _push(findings, 'EMPTY_OHLCV')
+    for idx, row in enumerate(rows, start=2):
+        if not all(k in row for k in required):
+            _push(findings, 'MISSING_OHLCV_COLUMN', idx)
+            continue
+        try:
+            stamp = _time(row['timestamp'])
+        except (ValueError, TypeError, OverflowError):
+            _push(findings, 'INVALID_TIMESTAMP', idx)
+            continue
+        if stamp in seen:
+            _push(findings, 'DUPLICATE_TIMESTAMP', idx)
+        seen.add(stamp)
+        if prior is not None:
+            if stamp <= prior:
+                _push(findings, 'NON_MONOTONIC_TIMESTAMP', idx)
+            if interval_seconds is not None and stamp > prior:
+                delta = (stamp-prior).total_seconds()
+                if delta != interval_seconds:
+                    _push(findings, 'IRREGULAR_CADENCE', idx, 'WARNING')
+        prior = stamp
+        try:
+            op, hi, lo, cl, vol = (_num(row[k]) for k in required[1:])
+        except (TypeError, ValueError, OverflowError):
+            _push(findings, 'INVALID_NUMERIC_FIELD', idx)
+            continue
+        if min(op, hi, lo, cl) <= 0 or vol < 0:
+            _push(findings, 'INVALID_PRICE_OR_VOLUME', idx)
+        if hi < max(op, cl, lo) or lo > min(op, cl, hi):
+            _push(findings, 'INVALID_CANDLE_GEOMETRY', idx)
+    return _base('ohlcv', findings, len(rows))
+
+
+def audit_ledger(rows):
+    findings = []
+    required = ('signal_bar_close', 'entry_time', 'next_bar_open')
+    if not rows:
+        _push(findings, 'EMPTY_LEDGER')
+    for idx, row in enumerate(rows, start=2):
+        if not all(k in row for k in required):
+            _push(findings, 'MISSING_LEDGER_COLUMN', idx)
+            continue
+        try:
+            signal, entry, next_open = (_time(row[k]) for k in required)
+        except (ValueError, TypeError, OverflowError):
+            _push(findings, 'INVALID_TIMESTAMP', idx)
+            continue
+        if entry <= signal:
+            _push(findings, 'LOOKAHEAD_OR_SAME_BAR_ENTRY', idx)
+        if next_open <= signal or entry < next_open:
+            _push(findings, 'NEXT_BAR_EXECUTION_VIOLATION', idx)
+        if (row.get('stop_hit', '').strip().lower() in ('true', '1', 'yes')
+                and row.get('target_hit', '').strip().lower() in ('true', '1', 'yes')):
+            _push(findings, 'AMBIGUOUS_SAME_BAR_EXIT', idx, 'WARNING')
+    return _base('ledger', findings, len(rows))
+
+
+def _pf(values):
+    gains = sum(x for x in values if x > 0)
+    losses = -sum(x for x in values if x < 0)
+    if not math.isfinite(gains) or not math.isfinite(losses):
+        return None
+    return round(gains / losses, 6) if losses and math.isfinite(gains/losses) else None
+
+
+def _compound_and_drawdown(values):
+    equity = peak = 1.0
+    worst = 0.0
+    for value in values:
+        if value <= -1:
+            return None, None
+        equity *= 1.0 + value
+        if not math.isfinite(equity):
+            return None, None
+        peak = max(peak, equity)
+        worst = max(worst, 1.0 - equity / peak)
+    return round(equity - 1, 6), round(worst, 6)
+
+
+def audit_stability(rows, costs=(0, 8, 20)):
+    findings, parsed = [], []
+    costs = tuple(costs)
+    if not costs or len(costs) > 20:
+        raise ValueError('invalid cost scenarios')
+    for cost in costs:
+        if not isinstance(cost, (float, int)) or not math.isfinite(cost) or cost < 0:
+            raise ValueError('cost must be finite and non-negative')
+    for idx, row in enumerate(rows, start=2):
+        try:
+            stamp = _time(row['exit_time'])
+            ret = _num(row['gross_return'])
+            if ret <= -1:
+                raise ValueError('return is -100% or less')
+        except (KeyError, ValueError, TypeError, OverflowError):
+            _push(findings, 'INVALID_TRADE_RETURN', idx)
+            continue
+        parsed.append((stamp, ret))
+    parsed.sort(key=lambda v: v[0])
+    if len(parsed) < 30:
+        _push(findings, 'LOW_TRADE_COUNT', severity='WARNING')
+    if len({(t.year, t.month) for t, _ in parsed}) < 3:
+        _push(findings, 'SHORT_TIME_COVERAGE', severity='WARNING')
+    metrics = {'interpretation': 'sequential non-overlapping, equal-equity trade proxy; not actual portfolio NAV'}
+    if parsed:
+        monthly = defaultdict(float)
+        for stamp, ret in parsed:
+            monthly[(stamp.year, stamp.month)] += ret
+        metrics['positive_month_fraction'] = round(sum(x > 0 for x in monthly.values())/len(monthly), 6)
+        metrics['excluded_invalid_trades'] = len(rows) - len(parsed)
+        for cost in costs:
+            net = [ret - cost/10000 for _, ret in parsed]
+            compound, mdd = _compound_and_drawdown(net)
+            if compound is None:
+                _push(findings, 'UNDEFINED_COMPOUNDING_COST_SCENARIO', severity='WARNING')
+            metrics[f'cost_{cost:g}bps'] = {
+                'trade_count': len(net),
+                'win_rate': round(sum(x > 0 for x in net)/len(net), 6),
+                'expectancy': round(sum(net)/len(net), 8),
+                'profit_factor': _pf(net),
+                'compounded_trade_return_proxy': compound,
+                'max_drawdown_proxy': mdd,
+            }
+    else:
+        _push(findings, 'NO_VALID_TRADES')
+    return _base('stability', findings, len(rows), metrics)

backtest_doctor/bundle.py

@@ -0,0 +1,38 @@
+"""Aggregation of independently audited, local CSV artifacts (never raw data)."""
+from __future__ import annotations
+
+from .audit import audit_ohlcv, audit_ledger, audit_stability
+
+
+def audit_bundle(*, ohlcv_rows, ledger_rows, stability_rows, interval_seconds=None):
+    """All three files are required; reports contain only aggregate diagnostics.
+
+    This does not establish independence, sufficient sample size or a genuine edge.
+    """
+    reports = {
+        'ohlcv': audit_ohlcv(ohlcv_rows, interval_seconds=interval_seconds),
+        'ledger': audit_ledger(ledger_rows),
+        'stability': audit_stability(stability_rows),
+    }
+    n_error = sum(v['errors'] for v in reports.values())
+    n_warn = sum(v['warnings'] for v in reports.values())
+    return {
+        'report_schema_version': '0.4',
+        'audit_type': 'bundle',
+        'status': 'FAIL' if n_error else ('WARN' if n_warn else 'PASS'),
+        'errors': n_error,
+        'warnings': n_warn,
+        'rows_examined': sum(v['rows_examined'] for v in reports.values()),
+        'findings': [
+            {'source': key, 'code': f['code'], 'severity': f['severity'], 'row': f['row']}
+            for key, report in reports.items() for f in report['findings']
+        ],
+        'metrics': {
+            'sections': {k: {'status': v['status'], 'errors': v['errors'],
+                             'warnings': v['warnings'], 'rows_examined': v['rows_examined']}
+                         for k, v in reports.items()},
+            'stability': reports['stability']['metrics'],
+            'interpretation': 'Independent static audits; passing does not prove causality or profitability',
+        },
+        'data_policy': 'aggregate-only; no raw inputs included',
+    }

backtest_doctor/cli.py

@@ -0,0 +1,92 @@
+"""Offline-only CLI. JSON and HTML reports redact input values and paths."""
+import argparse
+import csv
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .audit import audit_ledger, audit_ohlcv, audit_stability, read_csv
+from .bundle import audit_bundle
+from .report import render_html
+from .schema import load_columns, normalize_rows
+from .adapters import FORMATS, audit_imported_trades
+from .explain import explain_findings
+
+
+def _save_new_report(path, content):
+    """Exclusive creation prevents accidental overwrite and output symlink following."""
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY
+    if hasattr(os, 'O_NOFOLLOW'):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(path, flags, 0o600)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as out:
+            out.write(content)
+    except BaseException:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+        raise
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='backtest-doctor', description='Offline CSV backtest audit; no strategy execution or telemetry')
+    parser.add_argument('--version', action='version', version=__version__)
+    parser.add_argument('mode', choices=['ohlcv', 'ledger', 'stability', 'bundle', 'import-trades'])
+    parser.add_argument('file', type=Path, nargs='?')
+    parser.add_argument('--ohlcv-file', type=Path)
+    parser.add_argument('--ledger-file', type=Path)
+    parser.add_argument('--stability-file', type=Path)
+    parser.add_argument('--interval-seconds', type=int)
+    parser.add_argument('--framework', choices=sorted(FORMATS), help='Trade export CSV dialect (import-trades only)')
+    parser.add_argument('--additional-cost-bps', type=float, default=0.0, help='Extra hypothetical cost stress for import-trades; 0 means no new fees')
+    parser.add_argument('--html', type=Path, help='Create a privacy-minimal HTML report, without overwrite')
+    parser.add_argument('--columns', type=Path, help='Local JSON canonical-to-source column aliases')
+    parser.add_argument('--explain', action='store_true', help='Include data-free explanations for findings')
+    parser.add_argument('--fail-on-warn', action='store_true', help='Exit 1 for WARN as well as FAIL (CI mode)')
+    args = parser.parse_args(argv)
+    try:
+        columns = load_columns(args.columns) if args.columns is not None else {}
+        if args.mode != 'import-trades' and (args.framework is not None or args.additional_cost_bps != 0):
+            raise ValueError('framework settings require import-trades')
+        if args.mode == 'import-trades':
+            if (args.file is None or args.framework is None or args.columns is not None
+                    or args.interval_seconds is not None or any((args.ohlcv_file, args.ledger_file, args.stability_file))):
+                raise ValueError('import-trades requires CSV and framework only')
+            report = audit_imported_trades(read_csv(args.file), args.framework, args.additional_cost_bps)
+        elif args.mode == 'bundle':
+            if (args.file is not None or args.ohlcv_file is None or args.ledger_file is None
+                    or args.stability_file is None):
+                raise ValueError('bundle requires three named inputs and no positional file')
+            report = audit_bundle(
+                ohlcv_rows=normalize_rows(read_csv(args.ohlcv_file), 'ohlcv', columns),
+                ledger_rows=normalize_rows(read_csv(args.ledger_file), 'ledger', columns),
+                stability_rows=normalize_rows(read_csv(args.stability_file), 'stability', columns),
+                interval_seconds=args.interval_seconds,
+            )
+        else:
+            if args.file is None or any((args.ohlcv_file, args.ledger_file, args.stability_file)):
+                raise ValueError('invalid input selection')
+            rows = normalize_rows(read_csv(args.file), args.mode, columns)
+            if args.mode == 'ohlcv':
+                report = audit_ohlcv(rows, args.interval_seconds)
+            elif args.mode == 'ledger':
+                report = audit_ledger(rows)
+            else:
+                report = audit_stability(rows)
+        if args.explain:
+            explain_findings(report)
+        if args.html is not None:
+            _save_new_report(args.html, render_html(report))
+        print(json.dumps(report, allow_nan=False, sort_keys=True, separators=(',', ':')))
+        return 1 if report['status'] == 'FAIL' or (args.fail_on_warn and report['status'] == 'WARN') else 0
+    except (ValueError, OSError, UnicodeError, OverflowError, csv.Error):
+        print('AUDIT_ERROR: invalid or inaccessible input (details redacted)', file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

backtest_doctor/explain.py

@@ -0,0 +1,36 @@
+"""Fixed, data-free explanations for diagnostic finding codes.
+Descriptions never contain input rows, paths, identifiers, or timestamps.
+"""
+
+CATALOG = {
+    "EMPTY_OHLCV": ("No OHLCV rows were supplied.", "Export at least one timestamped candle and verify the input file is not empty."),
+    "MISSING_OHLCV_COLUMN": ("A candle row is missing one or more required OHLCV fields.", "Verify the exported header and column mapping; do not invent missing prices."),
+    "INVALID_TIMESTAMP": ("A timestamp is invalid or lacks an explicit timezone.", "Check the original time source and export timezone-aware ISO timestamps; never assume UTC."),
+    "DUPLICATE_TIMESTAMP": ("Two or more candle rows share a timestamp.", "Check whether duplicate candles represent duplicated imports or legitimate distinct intervals."),
+    "NON_MONOTONIC_TIMESTAMP": ("Candle timestamps did not increase strictly.", "Inspect the export ordering and any overlapping data partitions before sorting."),
+    "IRREGULAR_CADENCE": ("A positive interval differs from the declared cadence.", "Check sessions, exchange downtime, and missing bars; do not fill gaps without evidence."),
+    "INVALID_NUMERIC_FIELD": ("A required candle field is not a finite number.", "Check numeric formatting, missing values, and exporter conversions."),
+    "INVALID_PRICE_OR_VOLUME": ("A price is nonpositive or volume is negative.", "Check source adjustments, units, and upstream data quality; do not clamp values blindly."),
+    "INVALID_CANDLE_GEOMETRY": ("OHLC values violate high/low envelope consistency.", "Compare the candle to original source data and check adjustment/aggregation procedures."),
+    "EMPTY_LEDGER": ("No declared trade timing rows were supplied.", "Provide signal-close, entry, and next-open timestamps from a reproducible trade export."),
+    "MISSING_LEDGER_COLUMN": ("A trade timing row is missing a required timestamp field.", "Verify the ledger export and expected column names without synthesizing timing evidence."),
+    "LOOKAHEAD_OR_SAME_BAR_ENTRY": ("An entry was not strictly after the declared signal bar close.", "Reconcile indicator availability, decision timestamp, and execution timing; do not shift timestamps to hide the violation."),
+    "NEXT_BAR_EXECUTION_VIOLATION": ("Declared next-bar timing is inconsistent with the entry.", "Check the next executable bar open and ensure entry was not recorded before it."),
+    "AMBIGUOUS_SAME_BAR_EXIT": ("Stop and target are both declared hit within one bar.", "Use lower-timeframe or execution evidence and document the intrabar priority rule."),
+    "INVALID_TRADE_RETURN": ("A settled trade has an invalid timestamp or return.", "Check timezone, return units, and whether the record is settled; do not guess missing returns."),
+    "LOW_TRADE_COUNT": ("The sample contains fewer than 30 valid trades.", "Collect additional genuinely out-of-sample trades before interpreting stability measures."),
+    "SHORT_TIME_COVERAGE": ("Valid trades span fewer than three distinct calendar months.", "Extend the independent observation period; avoid treating a short window as robust evidence."),
+    "UNDEFINED_COMPOUNDING_COST_SCENARIO": ("A cost-stressed return cannot be compounded as a simple trade proxy.", "Inspect return-unit assumptions and cost magnitude; do not interpret the undefined proxy as account NAV."),
+    "NO_VALID_TRADES": ("No valid settled trade returns remained after validation.", "Check required fields and source export quality before computing performance metrics."),
+    "FINDING_LIMIT_REACHED": ("The diagnostics limit was reached.", "Address the first listed failures, then rerun on a bounded subset or corrected export."),
+    "SIGNAL_CAUSALITY_NOT_VERIFIED": ("The trade-summary CSV does not establish when signals became knowable.", "Supply a separately auditable signal-to-fill ledger before making causal claims."),
+}
+
+def explain_findings(report):
+    """Add an optional static guide only for emitted, recognized codes."""
+    codes = sorted({f["code"] for f in report["findings"] if f.get("code") in CATALOG})
+    report["explanations"] = [
+        {"code": code, "meaning": CATALOG[code][0], "next_step": CATALOG[code][1]}
+        for code in codes
+    ]
+    return report

backtest_doctor/report.py

@@ -0,0 +1,56 @@
+"""Standalone offline HTML reporting. Never embeds input rows or paths."""
+from html import escape
+import json
+
+
+def render_html(report):
+    """Render aggregate-only results using escaped values and zero external assets."""
+    title = escape(report['status'])
+    parts = []
+    sections = report.get('metrics', {}).get('sections', {})
+    for name, item in sections.items():
+        parts.append('<div class="section"><strong>'+escape(name.upper())+'</strong><span class="state">'
+                     +escape(item['status'])+'</span><small>Rows: '+str(item['rows_examined'])
+                     +' · Errors: '+str(item['errors'])+' · Warnings: '+str(item['warnings'])+'</small></div>')
+    rows = ''.join(
+        '<tr><td>'+escape(str(f.get('source','-')))+'</td><td>'+escape(f['code'])+
+        '</td><td>'+escape(f['severity'])+'</td><td>'+
+        escape(str(f['row']) if f['row'] is not None else '-')+'</td></tr>'
+        for f in report['findings']
+    )
+    explanations = report.get('explanations', [])
+    guide = ''.join(
+        '<section><h3>'+escape(str(item['code']))+'</h3><p>'+escape(str(item['meaning']))+
+        '</p><p><strong>Check:</strong> '+escape(str(item['next_step']))+'</p></section>'
+        for item in explanations
+    )
+    metrics = escape(json.dumps(report['metrics'], ensure_ascii=False, indent=2, sort_keys=True, allow_nan=False))
+    return ('''<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<title>Backtest Doctor — Audit</title>
+<style>:root{color-scheme:light}body{font:15px/1.6 system-ui, sans-serif;margin:0;background:#f4f7fb;color:#17253a}
+main{max-width:900px;margin:40px auto;padding:0 22px}h1{font-size:30px;margin:0}h2{font-size:18px;margin-top:28px}
+.kicker{color:#60738c;text-transform:uppercase;letter-spacing:.14em;font-size:11px;font-weight:700}
+.top{background:#142c48;color:#fff;padding:27px;border-radius:16px}.top p{color:#c7d9e8}
+.status{display:inline-block;background:#fff;color:#142c48;border-radius:8px;padding:5px 14px;font-weight:800}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(175px,1fr));gap:12px;margin-top:16px}
+.panel,.section{background:#fff;border:1px solid #dce5f1;border-radius:12px;padding:16px}
+.panel strong{display:block;font-size:24px}.panel span{font-size:12px;color:#60738c}
+.section{display:flex;gap:12px;align-items:center;margin-bottom:8px}.section small{color:#60738c;margin-left:auto}
+.state{background:#eaf0f7;border-radius:6px;padding:2px 8px;font-size:12px}
+table{border-collapse:collapse;background:white;width:100%;font-size:13px;overflow-wrap:anywhere}
+th,td{border-bottom:1px solid #dde7f1;padding:9px;text-align:left}
+pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#fff;border:1px solid #dce5f1;padding:16px;border-radius:10px}
+small,.foot{color:#60738c}details{margin-bottom:32px}
+</style></head><body><main><div class="top"><div class="kicker">Offline diagnostic report · no telemetry</div>
+<h1>Backtest Doctor</h1><p>Evidence checks are not proof of strategy profitability.</p>
+<span class="status">'''+title+'''</span></div><div class="grid">
+<div class="panel"><strong>'''+str(report['errors'])+'''</strong><span>Errors</span></div>
+<div class="panel"><strong>'''+str(report['warnings'])+'''</strong><span>Warnings</span></div>
+<div class="panel"><strong>'''+str(report['rows_examined'])+'''</strong><span>Rows examined</span></div></div>
+<h2>Sections</h2>'''+(''.join(parts) or '<p>No combined sections in this mode.</p>')+'''
+<h2>Evidence findings</h2><table><thead><tr><th>Mode</th><th>Code</th><th>Severity</th><th>Row</th></tr></thead><tbody>'''
++rows+'''</tbody></table>'''+('<h2>How to investigate</h2>'+guide if explanations else '')+'''<h2>Aggregate metrics</h2><details><summary>Show summary data</summary><pre>'''+metrics+'''</pre></details>
+<p class="foot">Input rows, filenames, identifiers, account data and strategy signals are excluded from the report.
+Metrics use simplifying assumptions. No external scripts, fonts, images or network requests.</p></main></body></html>''')

backtest_doctor/schema.py

@@ -0,0 +1,75 @@
+"""Offline, declarative CSV column aliases; never executes user configuration."""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+MAX_SCHEMA_BYTES = 16 * 1024
+CANONICAL_FIELDS = {
+    'ohlcv': frozenset(('timestamp', 'open', 'high', 'low', 'close', 'volume')),
+    'ledger': frozenset(('signal_bar_close', 'entry_time', 'next_bar_open',
+                         'stop_hit', 'target_hit')),
+    'stability': frozenset(('exit_time', 'gross_return')),
+}
+
+
+def _no_duplicate_keys(pairs):
+    result = {}
+    for name, value in pairs:
+        if name in result:
+            raise ValueError('duplicate JSON key')
+        result[name] = value
+    return result
+
+
+def load_columns(path):
+    """Read small trusted local JSON, rejecting duplicates and path symlinks."""
+    path = Path(path)
+    if path.is_symlink():
+        raise ValueError('symlink configuration rejected')
+    flags = os.O_RDONLY
+    if hasattr(os, 'O_NOFOLLOW'):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(path, flags)
+    with os.fdopen(fd, 'rb') as f:
+        info = os.fstat(f.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_SCHEMA_BYTES:
+            raise ValueError('invalid configuration file')
+        data = f.read(MAX_SCHEMA_BYTES + 1)
+        if len(data) > MAX_SCHEMA_BYTES:
+            raise ValueError('oversized configuration file')
+    document = json.loads(data.decode('utf-8-sig'), object_pairs_hook=_no_duplicate_keys)
+    if not isinstance(document, dict) or not document:
+        raise ValueError('invalid configuration structure')
+    result = {}
+    for mode, aliases in document.items():
+        if mode not in CANONICAL_FIELDS or not isinstance(aliases, dict) or not aliases:
+            raise ValueError('invalid configuration section')
+        if not set(aliases).issubset(CANONICAL_FIELDS[mode]):
+            raise ValueError('unknown canonical column')
+        for value in aliases.values():
+            if not isinstance(value, str) or not value.strip() or len(value) > 128:
+                raise ValueError('invalid source column name')
+        if len(set(aliases.values())) != len(aliases):
+            raise ValueError('ambiguous source column mapping')
+        result[mode] = aliases
+    return result
+
+
+def normalize_rows(rows, mode, columns):
+    """Rename headers without changing input values; reject collisions."""
+    aliases = columns.get(mode, {})
+    if not aliases:
+        return rows
+    normalized = []
+    for row in rows:
+        for canonical, original in aliases.items():
+            if original not in row or (canonical != original and canonical in row):
+                raise ValueError('missing or ambiguous mapped source column')
+        copy = dict(row)
+        for canonical, original in aliases.items():
+            copy[canonical] = copy[original]
+        normalized.append(copy)
+    return normalized

backtest_doctor-0.4.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: backtest-doctor
+Version: 0.4.0
+Summary: Offline backtest integrity checks for OHLCV, trade timing, and stability
+Author: suguobin2021
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/suguobin2021/backtest-doctor
+Project-URL: Documentation, https://github.com/suguobin2021/backtest-doctor/blob/main/docs/QUICKSTART.md
+Project-URL: Source, https://github.com/suguobin2021/backtest-doctor
+Project-URL: Issues, https://github.com/suguobin2021/backtest-doctor/issues
+Project-URL: Changelog, https://github.com/suguobin2021/backtest-doctor/blob/main/CHANGELOG.md
+Keywords: backtesting,audit,data-validation,lookahead-bias,trading,finance
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Backtest Doctor
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)
+
+**An offline, zero-runtime-dependency integrity check for exported backtests.** Validate timestamped OHLCV data, declared signal-to-fill timing, and how aggregate trade returns change under transaction costs. Produce deterministic, minimal JSON and self-contained HTML reports without including raw trades or filenames.
+
+> This tool checks the evidence you supply. It does **not** inspect or execute strategy source code; it cannot prove a strategy is free of look-ahead bias, overfitting, survivorship bias, or execution risk. `PASS` means only that the implemented checks found no violations in the supplied fields.
+
+## Install
+
+Requires Python 3.10+. The independently verified public package is currently a **prerelease**, not a stable release. Install the verified version explicitly:
+
+```sh
+python -m pip install --pre "backtest-doctor==0.4.0rc4"
+python -m backtest_doctor --version
+```
+
+Alternatively, install from the [audited GitHub Release](https://github.com/suguobin2021/backtest-doctor/releases/tag/v0.4.0rc4) or from this source checkout:
+
+```sh
+python -m pip install .
+python -m backtest_doctor --help
+```
+
+[PyPI project](https://pypi.org/project/backtest-doctor/0.4.0rc4/) · [Distribution guidance](docs/PYPI_PUBLISHING.md).
+
+## 30-second synthetic demo
+
+```sh
+# Run from the repository root; ALL sample files are synthetic.
+python -m backtest_doctor bundle \
+  --ohlcv-file examples/ohlcv_good.csv \
+  --ledger-file examples/ledger_bad.csv \
+  --stability-file examples/stability_demo.csv \
+  --html doctor-report.html --fail-on-warn
+```
+
+The intentionally bad ledger produces `FAIL` and exits **1**; this is expected, not an installation failure. Try `examples/ledger_good.csv` instead to see a clean causal timing check. Stability may still return `WARN` for small samples. The command exits `0` for PASS, `1` for FAIL (and WARN with `--fail-on-warn`), and `2` for rejected input. For an HTML report opened locally, use a **new filename**; the CLI will not overwrite an existing file.
+
+For a **complete cross-platform, beginner-friendly walkthrough**, follow [the synthetic quickstart](docs/QUICKSTART.md). For the manual, secretless PyPI publishing process, see [the distribution guide](docs/PYPI_PUBLISHING.md).
+
+For CI integration in other repositories, see the [experimental GitHub Action](docs/ACTION_USAGE.md).
+
+Verified public-only [three-framework format guide](docs/FRAMEWORK_COMPATIBILITY.md), [synthetic showcase](docs/SHOWCASE.md), [Android Termux guide](docs/TERMUX.md), and [changelog](CHANGELOG.md).
+
+Add `--explain` to any audit command for **fixed, data-free diagnostic explanations and investigation suggestions**. Explanations are opt-in, preserving the default JSON format. See the [finding guide](docs/FINDING_CODES.md).
+
+**NEW: experimental framework-export CSV adapters:** inspect settled trade summaries from `backtesting.py`, `vectorbt`, or a manually prepared Freqtrade CSV subset (not native Freqtrade ZIP/JSON):
+
+```sh
+python -m backtest_doctor import-trades examples/backtesting_py_synthetic.csv --framework backtesting-py
+python -m backtest_doctor import-trades examples/vectorbt_synthetic.csv --framework vectorbt
+python -m backtest_doctor import-trades examples/freqtrade_csv_synthetic.csv --framework freqtrade-csv
+```
+
+These checks cannot verify causal signal timing, and they do not double-count framework-reported costs by default. See [framework CSV contracts, known limits and privacy model](docs/FRAMEWORK_TRADES.md).
+
+For synthetic examples of alternate CSV column names (without copying any private exports), see [declarative column mapping](docs/COLUMN_MAPPING.md).
+
+## Checks
+
+| Mode | Input | Detects / summarizes |
+| --- | --- | --- |
+| `ohlcv` | CSV with `timestamp,open,high,low,close,volume` | Invalid candle geometry, duplicate/non-monotone timestamps, irregular cadence (when configured) |
+| `ledger` | CSV with `signal_bar_close,entry_time,next_bar_open` | Entry before or at signal close; entry before claimed next bar; both stop and target hit within the same bar |
+| `stability` | CSV with `exit_time,gross_return` | Trade count, time-coverage warnings, cost-scenario expectancy, PF, win rate, simplified sequential equity/drawdown proxies |
+| `bundle` | All three CSVs | All checks, one aggregate report and exit status |
+
+Single-mode invocation:
+
+```sh
+python -m backtest_doctor ohlcv examples/ohlcv_good.csv --interval-seconds 60
+python -m backtest_doctor ledger examples/ledger_bad.csv
+python -m backtest_doctor stability examples/stability_demo.csv
+```
+
+**Profit factor is undefined (reported as `null`) if no negative trades exist.** All stability returns are fractions: `0.01` means 1%. Compounded returns and drawdown are explicitly **proxies**, not portfolio NAV or account-level PnL. Overlapping trades, leverage, funding, slippage, execution limits and corporate actions are not reconstructed. Costs are specified in basis points per trade (default 0, 8, 20 bps).
+
+## Privacy model
+
+No networking, telemetry, trade execution, or strategy source evaluation. Reads local regular CSV files only (up to 10 MiB, 100,000 rows) and emits aggregate metrics and coded findings only. It is intentionally **not a security sandbox**: do not use it to evaluate untrusted adversarial filesystem access, and inspect reports before sharing. See [SECURITY.md](SECURITY.md).
+
+This repo uses synthetic fixtures only. It has no live trading records, private quantitative research databases, exchange API keys, real account IDs, strategy-specific parameters, server credentials, or licensed market datasets. Only explicitly allowlisted code, docs, tests, and synthetic fixtures are bundled by the build process.
+
+## Contribute and reproducibility
+
+```sh
+python -m unittest discover -s tests -v
+python -m pip wheel . --no-deps -w dist
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [docs/LIMITATIONS.md](docs/LIMITATIONS.md), and [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md). MIT-licensed. No claim of investment performance or financial advice.

backtest_doctor-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+backtest_doctor/__init__.py,sha256=nTIQFZSTonCECAWH-oW2CRaqkvS-3tlQ5TOHxUVC-HE,103
+backtest_doctor/__main__.py,sha256=ee5vE0xcUZM3fPmxicvcw-IJXkm6nOwxARREHBWpF8Q,47
+backtest_doctor/adapters.py,sha256=DV-83ElxXgk6reWkSPvRC0HjecK1QApSY8e-39R4vqk,3679
+backtest_doctor/audit.py,sha256=LznOMyje2vyL8jLelo85SYTwpIOrVq9DhzkytPNyCDI,9064
+backtest_doctor/bundle.py,sha256=MxscUW2JATGB5BHt7G0D3SpRP2fMtssk15ZkXE-TkaE,1736
+backtest_doctor/cli.py,sha256=KcWz5zuN2Io6cHiEWLsaN6u7KzQv5kDGxYwrN8rVlD4,4782
+backtest_doctor/explain.py,sha256=xLFvh1kf2rWXX8QinfQVHVHqkvnmDj3xknGoLYFKZOg,4245
+backtest_doctor/report.py,sha256=1JjTwlmX9MZMPGCzLX64kcN-4s0VoGeekoh0xsd18UY,4214
+backtest_doctor/schema.py,sha256=tIRuM-UzwDrbflFro2unMwm0ADMfwDIE5oXqSelgxP8,2903
+backtest_doctor-0.4.0.dist-info/licenses/LICENSE,sha256=BSP5cQzsOReke6y6KNmiVrZUZWdUs7TPaTm5MxJf4ow,1068
+backtest_doctor-0.4.0.dist-info/METADATA,sha256=zzjmNdgU6x_vuQ10EumcPxJAwdHxMVE0Xl5KFTCwLJA,7425
+backtest_doctor-0.4.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+backtest_doctor-0.4.0.dist-info/entry_points.txt,sha256=IOoRcp1cz6dUkeJqJzITn4JtrebjI5wmPnF9eDjKmeo,61
+backtest_doctor-0.4.0.dist-info/top_level.txt,sha256=c5VjrRGve1aSEQ42W3h_KrG-pOgq9nfljyczDH7Y4rE,16
+backtest_doctor-0.4.0.dist-info/RECORD,,

backtest_doctor-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

backtest_doctor-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+backtest-doctor = backtest_doctor.cli:main

backtest_doctor-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+Copyright (c) 2026 suguobin2021
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backtest_doctor-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+backtest_doctor