backtest-integrity-guard 0.2.1__py3-none-any.whl

backtest_integrity_guard/__init__.py

@@ -0,0 +1,2 @@
+"""Backtest Integrity Guard."""
+__version__ = "0.2.1"

backtest_integrity_guard/cli.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+from pathlib import Path
+
+from .core import audit_ohlcv_rows, audit_trade_rows, build_manifest, verify_manifest, parse_iso8601, sha256_file
+
+
+def read_csv(path: Path):
+    with path.open("r", encoding="utf-8-sig", newline="") as handle:
+        yield from csv.DictReader(handle)
+
+
+def emit(report) -> int:
+    print(report.to_json(), end="")
+    return 1 if report.errors else 0
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(prog="btguard")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    a = sub.add_parser("ohlcv", help="audit OHLCV geometry and timestamps")
+    a.add_argument("file", type=Path)
+    a.add_argument("--timestamp", default="timestamp")
+    a.add_argument("--map", type=Path, help="JSON mapping of canonical fields to input column names")
+    a.add_argument("--interval-seconds", type=int, help="Expected bar cadence in seconds")
+    a.add_argument(
+        "--allow-gaps", type=Path,
+        help="JSON list of explicit [from_timestamp, to_timestamp] session breaks",
+    )
+    a.add_argument("--hash-input", action="store_true", help="Include SHA256 of the audited input")
+
+    b = sub.add_parser("ledger", help="audit signal-to-execution causality")
+    b.add_argument("file", type=Path)
+    b.add_argument("--signal-close", default="signal_bar_close")
+    b.add_argument("--entry", default="entry_time")
+    b.add_argument("--next-open", default="next_bar_open")
+    b.add_argument("--hash-input", action="store_true", help="Include SHA256 of the audited input")
+
+    c = sub.add_parser("freeze", help="create a SHA256 input manifest")
+    c.add_argument("files", nargs="+", type=Path)
+    c.add_argument("-o", "--output", required=True, type=Path)
+    c.add_argument("--root", type=Path)
+
+    d = sub.add_parser("verify", help="verify a frozen SHA256 manifest")
+    d.add_argument("manifest", type=Path)
+    d.add_argument("--root", type=Path)
+
+    args = p.parse_args()
+    if args.command == "ohlcv":
+        mapping = None
+        if args.map:
+            mapping = json.loads(args.map.read_text(encoding="utf-8"))
+            if not isinstance(mapping, dict):
+                raise SystemExit("--map must contain a JSON object")
+
+        allowed_gaps = None
+        if args.allow_gaps:
+            raw = json.loads(args.allow_gaps.read_text(encoding="utf-8"))
+            if not isinstance(raw, list):
+                raise SystemExit("--allow-gaps must contain a JSON list")
+            try:
+                allowed_gaps = {
+                    (parse_iso8601(pair[0]), parse_iso8601(pair[1]))
+                    for pair in raw
+                    if isinstance(pair, list) and len(pair) == 2
+                }
+            except Exception as exc:
+                raise SystemExit(f"invalid --allow-gaps entry: {exc}") from exc
+            if len(allowed_gaps) != len(raw):
+                raise SystemExit("each --allow-gaps entry must be [from_timestamp, to_timestamp]")
+
+        report = audit_ohlcv_rows(
+            read_csv(args.file),
+            args.timestamp,
+            mapping,
+            args.interval_seconds,
+            allowed_gaps,
+        )
+        if args.hash_input:
+            report.input_sha256 = sha256_file(args.file)
+        return emit(report)
+    if args.command == "ledger":
+        report = audit_trade_rows(read_csv(args.file), args.signal_close, args.entry, args.next_open)
+        if args.hash_input:
+            report.input_sha256 = sha256_file(args.file)
+        return emit(report)
+    if args.command == "freeze":
+        data = build_manifest(args.files, args.root)
+        args.output.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        print(args.output)
+        return 0
+    return emit(verify_manifest(args.manifest, args.root))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backtest_integrity_guard/core.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from datetime import datetime, timedelta
+from pathlib import Path
+import hashlib
+import json
+from typing import Iterable, Mapping, Any
+
+from . import __version__
+
+
+REPORT_SCHEMA_VERSION = "1.0"
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str
+    code: str
+    row: int | None
+    message: str
+
+
+@dataclass
+class AuditReport:
+    findings: list[Finding]
+    input_sha256: str | None = None
+
+    @property
+    def errors(self) -> int:
+        return sum(x.severity == "ERROR" for x in self.findings)
+
+    @property
+    def warnings(self) -> int:
+        return sum(x.severity == "WARNING" for x in self.findings)
+
+    @property
+    def status(self) -> str:
+        return "FAIL" if self.errors else "PASS"
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "report_schema_version": REPORT_SCHEMA_VERSION,
+            "tool_version": __version__,
+            "status": self.status,
+            "errors": self.errors,
+            "warnings": self.warnings,
+            "findings": [asdict(x) for x in self.findings],
+        }
+        if self.input_sha256 is not None:
+            out["input_sha256"] = self.input_sha256
+        return out
+
+    def to_json(self) -> str:
+        return json.dumps(
+            self.to_dict(),
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        ) + "\n"
+
+
+def parse_iso8601(value: str) -> datetime:
+    text = value.strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    dt = datetime.fromisoformat(text)
+    if dt.tzinfo is None:
+        raise ValueError("timestamp must include UTC offset or Z")
+    return dt
+
+
+def _float(row: Mapping[str, str], key: str) -> float:
+    return float(row[key])
+
+
+def audit_ohlcv_rows(
+    rows: Iterable[Mapping[str, str]],
+    timestamp_field: str = "timestamp",
+    field_map: Mapping[str, str] | None = None,
+    expected_interval_seconds: int | None = None,
+    allowed_gaps: Iterable[tuple[datetime, datetime]] | None = None,
+) -> AuditReport:
+    findings: list[Finding] = []
+    seen: set[datetime] = set()
+    previous: datetime | None = None
+    if expected_interval_seconds is not None and expected_interval_seconds <= 0:
+        raise ValueError("expected_interval_seconds must be positive")
+    expected = (
+        timedelta(seconds=expected_interval_seconds)
+        if expected_interval_seconds is not None else None
+    )
+    allowed = set(allowed_gaps or ())
+    names = {
+        "timestamp": timestamp_field,
+        "open": "open",
+        "high": "high",
+        "low": "low",
+        "close": "close",
+        "volume": "volume",
+        **(dict(field_map) if field_map else {}),
+    }
+
+    for n, row in enumerate(rows, start=2):
+        missing = [k for k in ("timestamp", "open", "high", "low", "close") if names[k] not in row]
+        if missing:
+            findings.append(Finding(
+                "ERROR", "MISSING_REQUIRED_FIELD", n,
+                ",".join(f"{k}->{names[k]}" for k in missing),
+            ))
+            continue
+        try:
+            ts = parse_iso8601(row[names["timestamp"]])
+        except Exception as exc:
+            findings.append(Finding("ERROR", "INVALID_TIMESTAMP", n, str(exc)))
+            continue
+
+        if ts in seen:
+            findings.append(Finding("ERROR", "DUPLICATE_TIMESTAMP", n, str(ts)))
+        if previous is not None and ts <= previous:
+            findings.append(Finding("ERROR", "NON_MONOTONIC_TIME", n, str(ts)))
+        elif previous is not None and expected is not None:
+            delta = ts - previous
+            if delta != expected:
+                if (previous, ts) in allowed:
+                    findings.append(Finding(
+                        "WARNING", "ALLOWED_SESSION_GAP", n,
+                        f"from={previous.isoformat()} to={ts.isoformat()} seconds={int(delta.total_seconds())}",
+                    ))
+                elif delta > expected and delta.total_seconds() % expected.total_seconds() == 0:
+                    missing = int(delta / expected) - 1
+                    findings.append(Finding(
+                        "ERROR", "MISSING_BARS", n,
+                        f"missing={missing} expected_interval_seconds={expected_interval_seconds} "
+                        f"from={previous.isoformat()} to={ts.isoformat()}",
+                    ))
+                else:
+                    findings.append(Finding(
+                        "ERROR", "IRREGULAR_BAR_INTERVAL", n,
+                        f"expected_seconds={expected_interval_seconds} "
+                        f"actual_seconds={delta.total_seconds():g} "
+                        f"from={previous.isoformat()} to={ts.isoformat()}",
+                    ))
+        seen.add(ts)
+        previous = ts
+
+        try:
+            o, h, l, c = (_float(row, names[k]) for k in ("open", "high", "low", "close"))
+        except Exception as exc:
+            findings.append(Finding("ERROR", "INVALID_OHLC", n, str(exc)))
+            continue
+
+        if l > h:
+            findings.append(Finding("ERROR", "LOW_ABOVE_HIGH", n, f"{l}>{h}"))
+        if h < max(o, c):
+            findings.append(Finding("ERROR", "HIGH_BELOW_BODY", n, f"h={h} o={o} c={c}"))
+        if l > min(o, c):
+            findings.append(Finding("ERROR", "LOW_ABOVE_BODY", n, f"l={l} o={o} c={c}"))
+
+        volume_field = names["volume"]
+        if volume_field in row and row[volume_field] not in ("", None):
+            try:
+                if float(row[volume_field]) < 0:
+                    findings.append(Finding("ERROR", "NEGATIVE_VOLUME", n, row[volume_field]))
+            except Exception as exc:
+                findings.append(Finding("ERROR", "INVALID_VOLUME", n, str(exc)))
+
+        if "complete" in row and str(row["complete"]).strip().lower() in {"false", "0", "no"}:
+            findings.append(Finding("WARNING", "INCOMPLETE_BAR", n, "bar is marked incomplete"))
+
+    return AuditReport(findings)
+
+
+def audit_trade_rows(
+    rows: Iterable[Mapping[str, str]],
+    signal_close_field: str = "signal_bar_close",
+    entry_field: str = "entry_time",
+    next_open_field: str | None = "next_bar_open",
+) -> AuditReport:
+    findings: list[Finding] = []
+
+    for n, row in enumerate(rows, start=2):
+        try:
+            signal_close = parse_iso8601(row[signal_close_field])
+            entry = parse_iso8601(row[entry_field])
+        except Exception as exc:
+            findings.append(Finding("ERROR", "INVALID_EXECUTION_TIME", n, str(exc)))
+            continue
+
+        if entry <= signal_close:
+            findings.append(Finding(
+                "ERROR", "LOOKAHEAD_OR_SAME_BAR_ENTRY", n,
+                f"entry={entry.isoformat()} signal_close={signal_close.isoformat()}",
+            ))
+
+        if next_open_field and row.get(next_open_field):
+            try:
+                next_open = parse_iso8601(row[next_open_field])
+                if entry < next_open:
+                    findings.append(Finding(
+                        "ERROR", "ENTRY_BEFORE_NEXT_BAR", n,
+                        f"entry={entry.isoformat()} next_open={next_open.isoformat()}",
+                    ))
+            except Exception as exc:
+                findings.append(Finding("ERROR", "INVALID_NEXT_BAR_OPEN", n, str(exc)))
+
+        stop_hit = str(row.get("stop_hit", "")).strip().lower() in {"1", "true", "yes"}
+        target_hit = str(row.get("target_hit", "")).strip().lower() in {"1", "true", "yes"}
+        policy = str(row.get("same_bar_policy", "")).strip().lower()
+        if stop_hit and target_hit and policy not in {"stop_first", "target_first", "path_known"}:
+            findings.append(Finding(
+                "ERROR", "AMBIGUOUS_SAME_BAR_EXIT", n,
+                "stop and target both hit but no explicit same_bar_policy is declared",
+            ))
+
+    return AuditReport(findings)
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1 << 20), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def build_manifest(paths: Iterable[Path], root: Path | None = None) -> dict[str, Any]:
+    root = root.resolve() if root else None
+    files = []
+    for path in sorted(Path(p).resolve() for p in paths):
+        name = str(path.relative_to(root)) if root and path.is_relative_to(root) else str(path)
+        files.append({"path": name, "sha256": sha256_file(path), "bytes": path.stat().st_size})
+    return {"algorithm": "sha256", "files": files}
+
+
+def verify_manifest(manifest_path: Path, root: Path | None = None) -> AuditReport:
+    data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    base = root.resolve() if root else manifest_path.parent.resolve()
+    findings: list[Finding] = []
+    for item in data.get("files", []):
+        path = Path(item["path"])
+        if not path.is_absolute():
+            path = base / path
+        if not path.exists():
+            findings.append(Finding("ERROR", "MISSING_FROZEN_INPUT", None, str(path)))
+            continue
+        actual = sha256_file(path)
+        if actual != item["sha256"]:
+            findings.append(Finding("ERROR", "FROZEN_INPUT_HASH_MISMATCH", None, str(path)))
+    return AuditReport(findings)

backtest_integrity_guard-0.2.1.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: backtest-integrity-guard
+Version: 0.2.1
+Summary: Auditable checks for causal backtests, OHLCV data, execution timing, and frozen inputs.
+Home-page: https://github.com/suguobin2021/backtest-integrity-guard
+Author: suguobin2021
+License: MIT
+Project-URL: Source, https://github.com/suguobin2021/backtest-integrity-guard
+Project-URL: Issues, https://github.com/suguobin2021/backtest-integrity-guard/issues
+Project-URL: Releases, https://github.com/suguobin2021/backtest-integrity-guard/releases
+Project-URL: Changelog, https://github.com/suguobin2021/backtest-integrity-guard/blob/main/CHANGELOG.md
+Keywords: backtest,quantitative-finance,causality,lookahead-bias,ohlcv,data-validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Backtest Integrity Guard
+
+[![tests](https://github.com/suguobin2021/backtest-integrity-guard/actions/workflows/test.yml/badge.svg)](https://github.com/suguobin2021/backtest-integrity-guard/actions/workflows/test.yml)
+
+A small, dependency-free Python CLI for catching common integrity failures in quantitative backtests before performance metrics are trusted.
+
+It focuses on **causality, data integrity, explicit ambiguity handling, and reproducibility**. It does not implement trading signals or ship market data.
+
+## Install
+
+### From the v0.2.1 release wheel
+
+~~~bash
+python -m pip install "https://github.com/suguobin2021/backtest-integrity-guard/releases/download/v0.2.1/backtest_integrity_guard-0.2.1-py3-none-any.whl"
+btguard --help
+~~~
+
+The release also includes a source archive and SHA256SUMS.
+
+### From source
+
+~~~bash
+git clone https://github.com/suguobin2021/backtest-integrity-guard.git
+cd backtest-integrity-guard
+python -m pip install -e .
+~~~
+
+## Quick start
+
+Audit ordinary OHLCV data:
+
+~~~bash
+btguard ohlcv examples/ohlcv.csv --hash-input
+~~~
+
+Audit vendor-specific column names:
+
+~~~bash
+btguard ohlcv examples/vendor.csv --map examples/schema.json
+~~~
+
+Check a 5-minute cadence while explicitly allowing a known session break:
+
+~~~bash
+btguard ohlcv examples/session_gap.csv \
+  --interval-seconds 300 \
+  --allow-gaps examples/allowed_gaps.json
+~~~
+
+Audit signal-to-execution timing:
+
+~~~bash
+btguard ledger examples/trades.csv --hash-input
+~~~
+
+Freeze and verify research inputs:
+
+~~~bash
+btguard freeze examples/ohlcv.csv examples/trades.csv -o manifest.json --root .
+btguard verify manifest.json --root .
+~~~
+
+Commands exit non-zero when an integrity error is found, so they can be used in CI.
+
+## Output contract
+
+Audit output is deterministic JSON with a stable report schema:
+
+~~~json
+{
+  "errors": 0,
+  "findings": [],
+  "input_sha256": "<64 hex chars>",
+  "report_schema_version": "1.0",
+  "status": "PASS",
+  "tool_version": "0.2.1",
+  "warnings": 0
+}
+~~~
+
+Use --hash-input when a report should be bound to the exact audited file.
+
+## What it checks
+
+- OHLC geometry and negative or invalid volume
+- duplicate and non-monotonic timestamps
+- timezone-aware timestamps
+- incomplete-bar markers
+- configurable OHLCV schema aliases
+- missing bars and irregular cadence
+- explicitly allowlisted session gaps
+- signal-close to execution ordering
+- next-bar execution constraints
+- same-bar stop/target ambiguity
+- SHA256 frozen-input manifests
+- deterministic machine-readable reports
+
+## Scope
+
+Backtest Integrity Guard intentionally does **not** contain:
+- trading signals or alpha logic
+- brokerage execution code
+- proprietary or licensed market data
+- account credentials or API keys
+
+The goal is to make research assumptions machine-checkable without depending on any particular strategy.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports should include the smallest synthetic example that reproduces the problem.
+
+Useful project links:
+- [Issues](https://github.com/suguobin2021/backtest-integrity-guard/issues)
+- [Roadmap](ROADMAP.md)
+- [Changelog](CHANGELOG.md)
+- [Releases](https://github.com/suguobin2021/backtest-integrity-guard/releases)
+
+## License
+
+MIT.

backtest_integrity_guard-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+backtest_integrity_guard/__init__.py,sha256=LeVqnnEmPqlAaUWQq-agNioz640cOY6CpxTcD_5mTOY,54
+backtest_integrity_guard/cli.py,sha256=0nk_C1LO9LqOihgKZ-2vSYnVLKoDRpKLdlARh3erJ3Y,3880
+backtest_integrity_guard/core.py,sha256=aAD8zJdXd1B64fmI7gTM3mw_z8QwgDJ-In4iyYwuqas,9308
+backtest_integrity_guard-0.2.1.dist-info/licenses/LICENSE,sha256=TXrvWvqZRgag4u1EWmMHF14vNXd0x4jKgQ4uCfINIgw,1069
+backtest_integrity_guard-0.2.1.dist-info/METADATA,sha256=qXUr8DA_cY4PTE7tJG4LpFuahmJLdFW-Sq42BiOZhns,4493
+backtest_integrity_guard-0.2.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+backtest_integrity_guard-0.2.1.dist-info/entry_points.txt,sha256=ya8_pmtG3x_10GnctWOAE7LV6CAsMv7fskZvxts9tn8,62
+backtest_integrity_guard-0.2.1.dist-info/top_level.txt,sha256=dLGJUL6VFQiRsLozu0OEifPXjTNsMW5ywB5wksd2b6g,25
+backtest_integrity_guard-0.2.1.dist-info/RECORD,,

backtest_integrity_guard-0.2.1.dist-info/WHEEL

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

backtest_integrity_guard-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+btguard = backtest_integrity_guard.cli:main

backtest_integrity_guard-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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_integrity_guard-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+backtest_integrity_guard