tickbloom 0.1.0__py3-none-any.whl

tickbloom/__init__.py

@@ -0,0 +1,158 @@
+"""tickbloom — data integrity you can put in a document.
+
+    import tickbloom as tb
+    rep = tb.audit(df)
+    print(rep.score)          # 92.6
+    print(rep.breakdown.table())
+    rep.to_json("audit.json")
+
+Runs entirely in your process. Nothing is sent anywhere.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pandas as pd
+
+from . import checks as _checks
+from . import report as _report
+from . import scan as _scan
+from . import scoring as _scoring
+from .checks import Finding
+from .scan import scan
+from .scoring import ScoreBreakdown
+
+__version__ = "0.1.0"
+__all__ = ["audit", "scan", "export", "AuditReport", "Finding", "ScoreBreakdown", "__version__"]
+
+
+def _hash_frame(df: pd.DataFrame) -> str:
+    """Stable content hash of the input, for the manifest.
+
+    Uses pandas' row hasher rather than repr so the value does not depend on
+    display options or column ordering.
+    """
+    h = pd.util.hash_pandas_object(df[sorted(df.columns)], index=True).values
+    return hashlib.sha256(h.tobytes()).hexdigest()
+
+
+@dataclass
+class AuditReport:
+    findings: list[Finding]
+    breakdown: ScoreBreakdown
+    manifest: dict = field(default_factory=dict)
+
+    @property
+    def score(self) -> float:
+        return self.breakdown.score
+
+    @property
+    def verdict(self) -> str:
+        return self.breakdown.verdict
+
+    def failing(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == "fail"]
+
+    def to_dict(self) -> dict:
+        return {
+            "score": self.score,
+            "verdict": self.verdict,
+            "penalties": [p.__dict__ for p in self.breakdown.penalties],
+            "findings": [f.to_dict() for f in self.findings],
+            "manifest": self.manifest,
+        }
+
+    def to_html(self, **kwargs) -> str:
+        return _report.to_html(self, **kwargs)
+
+    def to_json(self, path: str | Path | None = None) -> str:
+        s = json.dumps(self.to_dict(), indent=2, sort_keys=True, default=str)
+        if path:
+            Path(path).write_text(s)
+        return s
+
+    def __repr__(self) -> str:
+        fails = len(self.failing())
+        flags = len([f for f in self.findings if f.severity == "flag"])
+        return (f"<AuditReport score={self.score} verdict={self.verdict} "
+                f"fail={fails} flag={flags}>")
+
+
+def audit(df: pd.DataFrame, *, calendar=None, code_path=None,
+          lookahead_failed: bool = False, survivorship_failed: bool = False,
+          weights: dict | None = None, source: str = "unspecified") -> AuditReport:
+    """Run the integrity suite and produce a scored, reproducible report.
+
+    Pass `code_path` to scan strategy source for look-ahead leaks in the same
+    call — the scanner's real findings then replace the hand-passed boolean,
+    which is what you want in anything other than a test.
+
+    lookahead_failed / survivorship_failed remain available for callers who
+    ran the scan separately or reconstruct the universe themselves. They are
+    structural verdicts, so the caller passes a boolean rather than a rate.
+    """
+    findings: list[Finding] = []
+    scan_findings: list[Finding] = []
+    if code_path is not None:
+        scan_findings = _scan.scan(code_path)
+        lookahead_failed = lookahead_failed or _scan.has_certain_leak(scan_findings)
+    for fn in _checks.ALL_CHECKS:
+        findings.append(fn(df, calendar) if fn is _checks.check_gaps else fn(df))
+
+    defects: dict[str, dict] = {f.check: {"rate": f.defect_rate} for f in findings}
+    defects["lookahead"] = {"failed": lookahead_failed}
+    defects["survivorship"] = {"failed": survivorship_failed}
+
+    if scan_findings:
+        # Real scanner output — specific files and lines — beats a placeholder.
+        findings.extend(scan_findings)
+    elif lookahead_failed:
+        findings.append(Finding(
+            id="TB-006", check="lookahead", severity="fail", failed=True,
+            title="Look-ahead leak reported by scanner",
+            description="A feature reads a value not observable at decision time. "
+                        "Any backtest using it trades on information it would not have had.",
+            impact="observed performance is fabricated; severe"))
+    if survivorship_failed:
+        findings.append(Finding(
+            id="TB-007", check="survivorship", severity="fail", failed=True,
+            title="Universe is not survivorship-adjusted",
+            description="Delisted symbols are absent from the historical universe, "
+                        "so the equity curve reflects only names that survived.",
+            impact="equity returns inflated 1-4% annually; severe"))
+
+    breakdown = _scoring.compute(defects, weights)
+
+    manifest = {
+        "tickbloom_version": __version__,
+        "scoring_version": _scoring.SCORING_VERSION,
+        "source": source,
+        "rows": int(len(df)),
+        "columns": sorted(df.columns.tolist()),
+        "input_sha256": _hash_frame(df),
+        "weights": {k: v["weight"] for k, v in (weights or _scoring.WEIGHTS).items()},
+        "tolerances": {k: v["tolerance"] for k, v in (weights or _scoring.WEIGHTS).items()},
+        "checks_run": sorted({f.check for f in findings}),
+        "code_scanned": str(code_path) if code_path else None,
+    }
+    return AuditReport(findings=findings, breakdown=breakdown, manifest=manifest)
+
+
+def export(report: AuditReport, path: str | Path, fmt: str = "html", **kwargs) -> Path:
+    """Write a report to disk in a sendable format.
+
+    `html` produces a single self-contained file with no external assets — it
+    opens from an email attachment on a locked-down laptop, which is where it
+    will actually be read.
+    """
+    fmt = fmt.lower()
+    if fmt == "html":
+        return _report.write_html(report, path, **kwargs)
+    if fmt == "json":
+        report.to_json(path)
+        return Path(path)
+    raise ValueError(f"unsupported format {fmt!r}; use 'html' or 'json'")

tickbloom/__main__.py

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

tickbloom/checks.py

@@ -0,0 +1,163 @@
+"""Integrity checks.
+
+Every check returns a Finding carrying the defect rate that scoring.py turns
+into points, plus enough locality (row indices, timestamps) that a user can go
+look at the offending data instead of taking our word for it.
+
+A check never raises on dirty data — dirty data is the input, not an error.
+It raises only on a malformed frame, which is a bug in the loader.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import pandas as pd
+
+REQUIRED_COLUMNS = ["ts_event", "symbol", "price", "size"]
+
+
+@dataclass
+class Finding:
+    id: str
+    check: str
+    severity: str              # pass | flag | fail
+    title: str
+    description: str
+    defect_rate: float | None = None
+    failed: bool = False
+    locations: list[Any] = field(default_factory=list)
+    impact: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id, "check": self.check, "severity": self.severity,
+            "title": self.title, "description": self.description,
+            "defect_rate": self.defect_rate, "failed": self.failed,
+            "locations": self.locations[:50], "impact": self.impact,
+        }
+
+
+def _validate(df: pd.DataFrame) -> None:
+    missing = [c for c in REQUIRED_COLUMNS if c not in df.columns]
+    if missing:
+        raise ValueError(f"frame is missing required columns: {missing}. "
+                         "Loaders must emit the normalized schema.")
+
+
+def _sev(rate: float, tol: float) -> str:
+    if rate == 0:
+        return "pass"
+    return "fail" if rate >= tol else "flag"
+
+
+def check_duplicates(df: pd.DataFrame) -> Finding:
+    """Identical (ts_event, price, size) appearing more than once."""
+    _validate(df)
+    dup_mask = df.duplicated(subset=["ts_event", "price", "size"], keep="first")
+    n = int(dup_mask.sum())
+    rate = n / len(df) if len(df) else 0.0
+    return Finding(
+        id="TB-002", check="duplicates", severity=_sev(rate, 0.005),
+        title=f"{n} duplicate ticks detected" if n else "No duplicate ticks",
+        description=(
+            "Identical timestamp, price, and size appearing more than once. "
+            "Duplicates inflate volume-weighted features and can double-count a "
+            "fill during replay."
+        ) if n else "No repeated (timestamp, price, size) triples in the sample.",
+        defect_rate=rate,
+        locations=df.index[dup_mask].tolist(),
+        impact="VWAP-family features biased; low unless rate is high" if n else "none",
+    )
+
+
+def check_order(df: pd.DataFrame) -> Finding:
+    """Timestamps that go backwards — breaks the causality assumption."""
+    _validate(df)
+    ts = pd.to_datetime(df["ts_event"], utc=True)
+    bad = ts.diff() < pd.Timedelta(0)
+    n = int(bad.sum())
+    rate = n / len(df) if len(df) else 0.0
+    return Finding(
+        id="TB-003", check="order", severity=_sev(rate, 0.001),
+        title=f"{n} out-of-order timestamps" if n else "Timestamps monotonic",
+        description=(
+            "A tick arrives with an earlier timestamp than its predecessor. Every "
+            "rolling feature assumes ordering, so this silently corrupts state."
+        ) if n else "ts_event is monotonically non-decreasing across the sample.",
+        defect_rate=rate,
+        locations=df.index[bad.fillna(False)].tolist(),
+        impact="rolling features computed on corrupted state; high" if n else "none",
+    )
+
+
+def check_zero_volume(df: pd.DataFrame) -> Finding:
+    """Prints with no size — they move indicators but were never tradeable."""
+    _validate(df)
+    bad = df["size"] <= 0
+    n = int(bad.sum())
+    rate = n / len(df) if len(df) else 0.0
+    return Finding(
+        id="TB-004", check="zero_volume", severity=_sev(rate, 0.01),
+        title=f"{n} zero-or-negative volume prints" if n else "All prints have size",
+        description=(
+            "Prints with no size still move price-based indicators but represent "
+            "nothing you could have traded."
+        ) if n else "No zero-or-negative size values.",
+        defect_rate=rate,
+        locations=df.index[bad].tolist(),
+        impact="indicators respond to untradeable prints; low" if n else "none",
+    )
+
+
+def check_gaps(df: pd.DataFrame, calendar: list | None = None) -> Finding:
+    """Sessions the calendar expects that the data does not contain."""
+    _validate(df)
+    ts = pd.to_datetime(df["ts_event"], utc=True)
+    present = set(ts.dt.date)
+    if calendar:
+        expected = {pd.Timestamp(d).date() for d in calendar}
+    else:
+        # Fall back to business days spanned by the sample. Documented as a
+        # weaker check — a real exchange calendar catches holidays correctly.
+        expected = set(pd.bdate_range(ts.min().date(), ts.max().date()).date)
+    missing = sorted(expected - present)
+    rate = len(missing) / len(expected) if expected else 0.0
+    return Finding(
+        id="TB-001", check="gaps", severity=_sev(rate, 0.02),
+        title=f"{len(missing)} expected sessions missing" if missing
+              else f"No gaps across {len(expected)} sessions",
+        description=(
+            "Sessions the calendar expects are absent from the data. Gaps silently "
+            "change the sample — a gap across a volatile week removes exactly the "
+            "periods that determine your tail risk."
+        ) if missing else "Every session in the expected calendar is present.",
+        defect_rate=rate,
+        locations=[str(d) for d in missing],
+        impact="tail risk understated; severe" if missing else "none",
+    )
+
+
+def check_session_border(df: pd.DataFrame, open_h: int = 13, close_h: int = 21) -> Finding:
+    """Prints outside the venue's published session window (UTC hours)."""
+    _validate(df)
+    ts = pd.to_datetime(df["ts_event"], utc=True)
+    bad = (ts.dt.hour < open_h) | (ts.dt.hour >= close_h)
+    n = int(bad.sum())
+    rate = n / len(df) if len(df) else 0.0
+    return Finding(
+        id="TB-005", check="session", severity=_sev(rate, 0.005),
+        title=f"{n} ticks outside session window" if n else "Session borders consistent",
+        description=(
+            f"Prints falling outside {open_h:02d}:00–{close_h:02d}:00 UTC. Overnight "
+            "activity leaking into a regular-hours frame contaminates open and close logic."
+        ) if n else "All prints fall inside the published session window.",
+        defect_rate=rate,
+        locations=df.index[bad].tolist(),
+        impact="open/close features contaminated; moderate" if n else "none",
+    )
+
+
+ALL_CHECKS = [check_gaps, check_order, check_duplicates,
+              check_zero_volume, check_session_border]

tickbloom/cli.py

@@ -0,0 +1,183 @@
+"""Command-line entry point.
+
+    python -m tickbloom audit data.csv -o report.html
+
+Built for the concierge audits in Phase 0: someone sends you a CSV, you run one
+command, you send back an HTML file. The whole loop should take under a minute,
+because you are going to do it five times before you write another line of
+product code.
+
+Column mapping is deliberately forgiving. Real exports from real traders have
+columns called `timestamp`, `datetime`, `Date`, `px`, `last`, `qty`, `volume`.
+Making them rename columns before you can help them is how a free audit turns
+into an unanswered email.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Common aliases seen in the wild -> our normalized schema.
+ALIASES = {
+    "ts_event": ["ts_event", "timestamp", "datetime", "date", "time", "ts", "dt"],
+    "symbol": ["symbol", "ticker", "instrument", "contract", "sym"],
+    "price": ["price", "px", "last", "close", "trade_price"],
+    "size": ["size", "qty", "quantity", "volume", "vol", "amount"],
+}
+
+
+def normalize_columns(df, verbose: bool = True):
+    """Map whatever they sent us onto the normalized schema."""
+    lower = {c.lower().strip(): c for c in df.columns}
+    mapping, missing = {}, []
+    for target, options in ALIASES.items():
+        hit = next((lower[o] for o in options if o in lower), None)
+        if hit:
+            if hit != target:
+                mapping[hit] = target
+        else:
+            missing.append(target)
+
+    if mapping:
+        df = df.rename(columns=mapping)
+        if verbose:
+            for src, dst in mapping.items():
+                print(f"  mapped column {src!r} -> {dst!r}")
+
+    if "symbol" in missing:
+        df["symbol"] = "UNKNOWN"
+        missing.remove("symbol")
+        if verbose:
+            print("  no symbol column — defaulting to 'UNKNOWN'")
+
+    if missing:
+        cols = ", ".join(repr(c) for c in df.columns)
+        sys.exit(
+            f"error: could not find a column for {missing}.\n"
+            f"       columns present: {cols}\n"
+            f"       rename them, or add an alias in tickbloom/cli.py"
+        )
+    return df
+
+
+def cmd_audit(args) -> int:
+    import pandas as pd
+
+    import tickbloom as tb
+    from tickbloom import report as tb_report
+
+    src = Path(args.input)
+    if not src.exists():
+        sys.exit(f"error: no such file: {src}")
+
+    print(f"reading {src.name}…")
+    if src.suffix.lower() in (".parquet", ".pq"):
+        df = pd.read_parquet(src)
+    else:
+        df = pd.read_csv(src)
+    print(f"  {len(df):,} rows, {len(df.columns)} columns")
+
+    df = normalize_columns(df, verbose=True)
+
+    if args.code:
+        print(f"scanning {args.code} for look-ahead leaks…")
+
+    rep = tb.audit(
+        df,
+        code_path=args.code,
+        source=args.source or src.name,
+        lookahead_failed=args.lookahead_failed,
+        survivorship_failed=args.survivorship_failed,
+    )
+
+    print()
+    print(rep.breakdown.table())
+    print()
+
+    fails = rep.failing()
+    if fails:
+        print("BLOCKING FINDINGS")
+        for f in fails:
+            print(f"  [{f.id}] {f.title}")
+        print()
+
+    out = Path(args.output)
+    tb_report.write_html(
+        rep, out,
+        subject=args.source or src.name,
+        generated=args.generated or "",
+    )
+    print(f"wrote {out}  ({out.stat().st_size:,} bytes)")
+
+    if args.json:
+        rep.to_json(args.json)
+        print(f"wrote {args.json}")
+
+    # Exit code carries the verdict so this composes in CI.
+    if args.fail_under is not None and rep.score < args.fail_under:
+        print(f"\nFAIL: score {rep.score} is below --fail-under {args.fail_under}")
+        return 1
+    return 0
+
+
+def cmd_scan(args) -> int:
+    from tickbloom.scan import scan
+
+    findings = scan(args.path)
+    if not findings:
+        print(f"no look-ahead patterns found in {args.path}")
+        return 0
+
+    for f in findings:
+        mark = "FAIL" if f.severity == "fail" else "FLAG"
+        print(f"\n[{mark}] {f.id}  {f.title}")
+        print(f"  {f.description}")
+        for loc in f.locations[:20]:
+            print(f"    {loc}")
+        if len(f.locations) > 20:
+            print(f"    … and {len(f.locations) - 20} more")
+
+    certain = [f for f in findings if f.severity == "fail"]
+    print(f"\n{len(certain)} certain, {len(findings) - len(certain)} likely")
+    if certain:
+        print("Suppress intentional forward-looking code with:  # tickbloom: allow")
+    return 1 if certain else 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="tickbloom",
+        description="Validate market data and produce a sendable audit report.",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    a = sub.add_parser("audit", help="audit a CSV or Parquet file")
+    a.add_argument("input", help="path to .csv or .parquet")
+    a.add_argument("-o", "--output", default="audit-report.html",
+                   help="HTML report path (default: audit-report.html)")
+    a.add_argument("--json", help="also write the raw report as JSON")
+    a.add_argument("--source", help="label for the report header, e.g. 'databento:ES.c.0'")
+    a.add_argument("--generated", help="timestamp to stamp on the report; "
+                                       "omit to keep output byte-reproducible")
+    a.add_argument("--fail-under", type=float,
+                   help="exit 1 if the score falls below this (for CI)")
+    a.add_argument("--code", help="also scan a strategy file or directory for "
+                                  "look-ahead leaks and fold the result in")
+    a.add_argument("--lookahead-failed", action="store_true",
+                   help="record a look-ahead leak reported by an external scan")
+    a.add_argument("--survivorship-failed", action="store_true",
+                   help="record that the universe is not survivorship-adjusted")
+    a.set_defaults(func=cmd_audit)
+
+    sc = sub.add_parser("scan", help="scan Python source for look-ahead leaks")
+    sc.add_argument("path", help="a .py file or a directory")
+    sc.set_defaults(func=cmd_scan)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())