tickbloom 0.1.0__tar.gz

tickbloom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tickbloom
+
+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.

tickbloom-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: tickbloom
+Version: 0.1.0
+Summary: Market-data integrity scoring and look-ahead detection for quantitative Python.
+Project-URL: Homepage, https://tickbloom.com
+Project-URL: Documentation, https://tickbloom.com
+Project-URL: Source, https://github.com/tickbloom/tickbloom
+Project-URL: Issues, https://github.com/tickbloom/tickbloom/issues
+Author: Tickbloom
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,backtesting,data-quality,look-ahead,market-data,quant,quantitative-finance,survivorship-bias,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tickbloom
+
+Data integrity you can put in a document.
+
+Runs entirely in your own process. Your data, your strategy code, and your fills never leave the machine.
+
+## Quickstart
+
+```python
+import pandas as pd
+import tickbloom as tb
+
+df = pd.read_parquet("es_2024q3.parquet")   # ts_event, symbol, price, size
+
+rep = tb.audit(df, source="databento:ES.c.0")
+print(rep)                    # <AuditReport score=92.6 verdict=review fail=0 flag=2>
+print(rep.breakdown.table())  # where every deducted point went
+rep.to_json("audit.json")     # reproducible, byte-stable
+```
+
+```
+check          weight      rate      tol    -pts
+------------------------------------------------
+gaps               25   0.5000%    2.00%    5.53
+duplicates         10   0.1000%    0.50%    1.81
+order              15   0.0000%    0.10%    0.00
+lookahead          25structural        —    0.00
+survivorship       10structural        —    0.00
+session            10   0.0000%    0.50%    0.00
+zero_volume         5   0.0000%    1.00%    0.00
+------------------------------------------------
+SCORE                                           92.6
+```
+
+## What the score promises
+
+Three properties, each with a test in `tests/test_scoring.py`:
+
+1. **Deterministic** — same frame, same config, same float. No sampling, no wall-clock, no dependence on column or dict ordering.
+2. **Decomposable** — `score = 100 - sum(penalties)`. Every point is attributable to one check. When an allocator asks where 7.4 points went, you print the table.
+3. **Explainable in one sentence per check** — if a weight can't be justified to a trader in one sentence, the weight is wrong.
+
+Weights are declared in `scoring.WEIGHTS`, recorded in every manifest, and overridable. That's deliberate: a fund should be able to say *"we used these thresholds"*, not *"the vendor decided."*
+
+## Weights and why
+
+| Check | Weight | One-sentence rationale |
+|---|---|---|
+| `lookahead` | 25 | Directly fabricates returns; a single leaked bar can turn a losing strategy into a plausible winner. |
+| `gaps` | 25 | Missing sessions silently change the sample — a gap across a crash removes exactly the periods that set your tail risk. |
+| `order` | 15 | Out-of-order timestamps break the causality assumption every feature is built on. |
+| `survivorship` | 10 | Delisted names removed from the universe inflate equity returns 1–4% annually. |
+| `duplicates` | 10 | Double-counted prints bias volume-weighted features and can double-fill in replay. |
+| `session` | 10 | Overnight prints leaking into a regular-hours frame contaminate open/close logic. |
+| `zero_volume` | 5 | Phantom prints move indicators without being tradeable, but rarely dominate a result. |
+
+## The penalty curve
+
+```
+penalty = weight * (1 - exp(-defect_rate / tolerance))
+```
+
+Not `weight * min(1, rate/tolerance)`. The linear clip was the first implementation and it was wrong: in a 1,000-row sample a **single** out-of-order tick is a 0.1% rate, which equals the tolerance exactly and deducted the entire 15-point weight for one bad tick. Small samples were being destroyed by single defects.
+
+Published reference points, asserted in tests:
+
+| Defect rate | Share of weight deducted |
+|---|---|
+| 0.25 × tolerance | 22% |
+| 1.0 × tolerance | 63% |
+| 3.0 × tolerance | 95% |
+| 5.0 × tolerance | 99% (treated as full) |
+
+Structural checks (`lookahead`, `survivorship`) stay binary. A "small" look-ahead leak is not a thing.
+
+## Look-ahead scanning
+
+```bash
+python -m tickbloom scan strategies/          # exit 1 if a certain leak exists
+python -m tickbloom audit data.csv --code strategies/ -o report.html
+```
+
+A static AST pass over your source. Eight rules, each declaring a **confidence**, because a static analyser dies from false positives rather than missed detections:
+
+| Confidence | Severity | Meaning |
+|---|---|---|
+| `certain` | `fail` | A leak by definition. `close.shift(-1)` is tomorrow's close; there is no other reading. |
+| `likely` | `flag` | Usually a leak, but has legitimate uses — label construction, offline research. |
+
+Only `certain` rules can fail an audit. A false `fail` costs you the user; a false `flag` costs them four seconds.
+
+Forward-looking code is *correct* when building labels, so suppress per line:
+
+```python
+df["target_1d"] = close.shift(-1)   # tickbloom: allow
+df["target_1d"] = close.shift(-1)   # tickbloom: allow TB-101
+```
+
+Without this, every supervised-learning codebase reports dozens of findings on its target construction and the tool gets uninstalled on day one.
+
+**Limits, stated plainly.** This is a syntactic pass. It cannot see through a variable holding a shift amount, a leak inside a library you call, or one assembled at runtime. It catches the common written-down forms. TB-108 does one-pass tracking of names bound to `.shift(n>0)` so it stays quiet on code that lagged correctly upstream — but it is reported as `likely`, not `certain`, precisely because that analysis is shallow.
+
+## Sending a report
+
+```bash
+python -m tickbloom audit their-file.csv -o report.html --source "ES · 2024-H1"
+```
+
+Produces a self-contained HTML file — no external assets, no scripts, no network — that opens from an email attachment on a locked-down laptop. The column mapper handles `Datetime`/`Px`/`Qty`/`Ticker` and the usual variants, so nobody has to rename anything first.
+
+```python
+rep = tb.audit(df)
+tb.export(rep, "report.html")               # sendable document
+tb.export(rep, "report.json", fmt="json")   # machine-readable
+```
+
+Reports are **byte-reproducible**: same input, same bytes out. No timestamp is stamped unless you pass `generated=` explicitly. A document whose bytes change when nothing changed is not evidence, and `test_html_is_byte_reproducible` fails the build if that regresses.
+
+`--fail-under 95` exits 1 below a threshold, so the CLI composes into CI today.
+
+## Status
+
+Implemented: the five integrity checks, the scoring model, the static look-ahead scanner, the report object, the reproducibility manifest, HTML/JSON export, and the CLI.
+
+Not yet: loaders (`load()`), the runtime look-ahead guard, PDF export, the robustness agent, and the GitHub Action.
+
+## Tests
+
+```
+python -m pytest tests/ -q     # 69 passed
+```
+
+## A note on scope
+
+This does not replace QuantConnect or Lean. It sits upstream of whatever backtester you already use, and it does not assert compliance with, certification by, or approval from any trading firm. It produces evidence. A human draws the conclusion.

tickbloom-0.1.0/README.md

@@ -0,0 +1,135 @@
+# tickbloom
+
+Data integrity you can put in a document.
+
+Runs entirely in your own process. Your data, your strategy code, and your fills never leave the machine.
+
+## Quickstart
+
+```python
+import pandas as pd
+import tickbloom as tb
+
+df = pd.read_parquet("es_2024q3.parquet")   # ts_event, symbol, price, size
+
+rep = tb.audit(df, source="databento:ES.c.0")
+print(rep)                    # <AuditReport score=92.6 verdict=review fail=0 flag=2>
+print(rep.breakdown.table())  # where every deducted point went
+rep.to_json("audit.json")     # reproducible, byte-stable
+```
+
+```
+check          weight      rate      tol    -pts
+------------------------------------------------
+gaps               25   0.5000%    2.00%    5.53
+duplicates         10   0.1000%    0.50%    1.81
+order              15   0.0000%    0.10%    0.00
+lookahead          25structural        —    0.00
+survivorship       10structural        —    0.00
+session            10   0.0000%    0.50%    0.00
+zero_volume         5   0.0000%    1.00%    0.00
+------------------------------------------------
+SCORE                                           92.6
+```
+
+## What the score promises
+
+Three properties, each with a test in `tests/test_scoring.py`:
+
+1. **Deterministic** — same frame, same config, same float. No sampling, no wall-clock, no dependence on column or dict ordering.
+2. **Decomposable** — `score = 100 - sum(penalties)`. Every point is attributable to one check. When an allocator asks where 7.4 points went, you print the table.
+3. **Explainable in one sentence per check** — if a weight can't be justified to a trader in one sentence, the weight is wrong.
+
+Weights are declared in `scoring.WEIGHTS`, recorded in every manifest, and overridable. That's deliberate: a fund should be able to say *"we used these thresholds"*, not *"the vendor decided."*
+
+## Weights and why
+
+| Check | Weight | One-sentence rationale |
+|---|---|---|
+| `lookahead` | 25 | Directly fabricates returns; a single leaked bar can turn a losing strategy into a plausible winner. |
+| `gaps` | 25 | Missing sessions silently change the sample — a gap across a crash removes exactly the periods that set your tail risk. |
+| `order` | 15 | Out-of-order timestamps break the causality assumption every feature is built on. |
+| `survivorship` | 10 | Delisted names removed from the universe inflate equity returns 1–4% annually. |
+| `duplicates` | 10 | Double-counted prints bias volume-weighted features and can double-fill in replay. |
+| `session` | 10 | Overnight prints leaking into a regular-hours frame contaminate open/close logic. |
+| `zero_volume` | 5 | Phantom prints move indicators without being tradeable, but rarely dominate a result. |
+
+## The penalty curve
+
+```
+penalty = weight * (1 - exp(-defect_rate / tolerance))
+```
+
+Not `weight * min(1, rate/tolerance)`. The linear clip was the first implementation and it was wrong: in a 1,000-row sample a **single** out-of-order tick is a 0.1% rate, which equals the tolerance exactly and deducted the entire 15-point weight for one bad tick. Small samples were being destroyed by single defects.
+
+Published reference points, asserted in tests:
+
+| Defect rate | Share of weight deducted |
+|---|---|
+| 0.25 × tolerance | 22% |
+| 1.0 × tolerance | 63% |
+| 3.0 × tolerance | 95% |
+| 5.0 × tolerance | 99% (treated as full) |
+
+Structural checks (`lookahead`, `survivorship`) stay binary. A "small" look-ahead leak is not a thing.
+
+## Look-ahead scanning
+
+```bash
+python -m tickbloom scan strategies/          # exit 1 if a certain leak exists
+python -m tickbloom audit data.csv --code strategies/ -o report.html
+```
+
+A static AST pass over your source. Eight rules, each declaring a **confidence**, because a static analyser dies from false positives rather than missed detections:
+
+| Confidence | Severity | Meaning |
+|---|---|---|
+| `certain` | `fail` | A leak by definition. `close.shift(-1)` is tomorrow's close; there is no other reading. |
+| `likely` | `flag` | Usually a leak, but has legitimate uses — label construction, offline research. |
+
+Only `certain` rules can fail an audit. A false `fail` costs you the user; a false `flag` costs them four seconds.
+
+Forward-looking code is *correct* when building labels, so suppress per line:
+
+```python
+df["target_1d"] = close.shift(-1)   # tickbloom: allow
+df["target_1d"] = close.shift(-1)   # tickbloom: allow TB-101
+```
+
+Without this, every supervised-learning codebase reports dozens of findings on its target construction and the tool gets uninstalled on day one.
+
+**Limits, stated plainly.** This is a syntactic pass. It cannot see through a variable holding a shift amount, a leak inside a library you call, or one assembled at runtime. It catches the common written-down forms. TB-108 does one-pass tracking of names bound to `.shift(n>0)` so it stays quiet on code that lagged correctly upstream — but it is reported as `likely`, not `certain`, precisely because that analysis is shallow.
+
+## Sending a report
+
+```bash
+python -m tickbloom audit their-file.csv -o report.html --source "ES · 2024-H1"
+```
+
+Produces a self-contained HTML file — no external assets, no scripts, no network — that opens from an email attachment on a locked-down laptop. The column mapper handles `Datetime`/`Px`/`Qty`/`Ticker` and the usual variants, so nobody has to rename anything first.
+
+```python
+rep = tb.audit(df)
+tb.export(rep, "report.html")               # sendable document
+tb.export(rep, "report.json", fmt="json")   # machine-readable
+```
+
+Reports are **byte-reproducible**: same input, same bytes out. No timestamp is stamped unless you pass `generated=` explicitly. A document whose bytes change when nothing changed is not evidence, and `test_html_is_byte_reproducible` fails the build if that regresses.
+
+`--fail-under 95` exits 1 below a threshold, so the CLI composes into CI today.
+
+## Status
+
+Implemented: the five integrity checks, the scoring model, the static look-ahead scanner, the report object, the reproducibility manifest, HTML/JSON export, and the CLI.
+
+Not yet: loaders (`load()`), the runtime look-ahead guard, PDF export, the robustness agent, and the GitHub Action.
+
+## Tests
+
+```
+python -m pytest tests/ -q     # 69 passed
+```
+
+## A note on scope
+
+This does not replace QuantConnect or Lean. It sits upstream of whatever backtester you already use, and it does not assert compliance with, certification by, or approval from any trading firm. It produces evidence. A human draws the conclusion.

tickbloom-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tickbloom"
+version = "0.1.0"
+description = "Market-data integrity scoring and look-ahead detection for quantitative Python."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Tickbloom" }]
+keywords = [
+    "quant", "quantitative-finance", "backtesting", "market-data",
+    "data-quality", "look-ahead", "survivorship-bias", "trading", "audit",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Developers",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Software Development :: Quality Assurance",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pandas>=2.0",
+    "pyarrow>=14.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "build", "twine"]
+
+[project.scripts]
+tickbloom = "tickbloom.cli:main"
+
+[project.urls]
+Homepage = "https://tickbloom.com"
+Documentation = "https://tickbloom.com"
+Source = "https://github.com/tickbloom/tickbloom"
+Issues = "https://github.com/tickbloom/tickbloom/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tickbloom"]
+
+[tool.hatch.build.targets.sdist]
+include = ["tickbloom", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tickbloom-0.1.0/tests/test_report.py

@@ -0,0 +1,143 @@
+"""Tests for the sendable report.
+
+The load-bearing test here is `test_html_is_byte_reproducible`. An audit
+document whose bytes change when nothing changed is not evidence — if that
+property breaks, the whole "you can defend this" pitch breaks with it.
+"""
+
+import re
+
+import pandas as pd
+import pytest
+
+import tickbloom as tb
+from tests.test_scoring import clean_frame
+
+
+def dirty_frame():
+    """Known defects: 4 duplicates, one dropped session, one bad timestamp."""
+    df = clean_frame()
+    df = pd.concat([df, df.iloc[[5, 6, 7, 8]]], ignore_index=True)
+    df = df[pd.to_datetime(df["ts_event"]).dt.date != pd.Timestamp("2024-07-10").date()]
+    return df.reset_index(drop=True)
+
+
+# ---------- reproducibility ----------
+
+def test_html_is_byte_reproducible():
+    rep = tb.audit(dirty_frame())
+    assert rep.to_html() == rep.to_html()
+
+
+def test_html_has_no_implicit_timestamp():
+    """No wall-clock leaks in unless the caller asks for one."""
+    html = tb.audit(clean_frame()).to_html()
+    assert not re.search(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}", html), \
+        "an implicit timestamp would break byte reproducibility"
+
+
+def test_generated_timestamp_is_opt_in():
+    html = tb.audit(clean_frame()).to_html(generated="2026-08-25T09:00:00Z")
+    assert "2026-08-25T09:00:00Z" in html
+
+
+def test_two_identical_frames_produce_identical_documents():
+    a = tb.audit(dirty_frame(), source="x").to_html()
+    b = tb.audit(dirty_frame(), source="x").to_html()
+    assert a == b
+
+
+# ---------- content ----------
+
+def test_report_contains_score_and_verdict():
+    rep = tb.audit(clean_frame())
+    html = rep.to_html()
+    assert "100.0" in html
+    assert ">Pass<" in html
+
+
+def test_failing_audit_renders_fail_verdict():
+    rep = tb.audit(clean_frame(), lookahead_failed=True)
+    html = rep.to_html()
+    assert ">Fail<" in html
+    assert "Look-ahead" in html
+
+
+def test_every_finding_appears():
+    rep = tb.audit(dirty_frame())
+    html = rep.to_html()
+    for f in rep.findings:
+        assert f.id in html, f"{f.id} missing from the rendered report"
+
+
+def test_penalty_table_shows_arithmetic():
+    rep = tb.audit(dirty_frame())
+    html = rep.to_html()
+    assert "Where the points went" in html
+    for p in rep.breakdown.penalties:
+        assert p.check in html
+
+
+def test_manifest_is_rendered():
+    html = tb.audit(clean_frame(), source="databento:ES").to_html()
+    assert "input_sha256" in html
+    assert "databento:ES" in html
+
+
+def test_disclaimer_present():
+    """The one sentence that must never be dropped."""
+    html = tb.audit(clean_frame()).to_html()
+    assert "not a certification" in html
+    assert "any trading firm or regulator" in html
+
+
+# ---------- safety ----------
+
+def test_self_contained_no_network():
+    html = tb.audit(clean_frame()).to_html()
+    for bad in ["http://", "https://fonts", "<script", "src="]:
+        assert bad not in html, f"report must be self-contained; found {bad!r}"
+
+
+def test_source_label_is_escaped():
+    """A crafted source label must not inject markup."""
+    rep = tb.audit(clean_frame(), source="<img src=x onerror=alert(1)>")
+    html = rep.to_html()
+    assert "<img src=x" not in html
+    assert "&lt;img" in html
+
+
+# ---------- export ----------
+
+def test_export_html_writes_file(tmp_path):
+    rep = tb.audit(dirty_frame())
+    out = tb.export(rep, tmp_path / "r.html")
+    assert out.exists() and out.stat().st_size > 2000
+    assert out.read_text().startswith("<!DOCTYPE html>")
+
+
+def test_export_json_writes_file(tmp_path):
+    rep = tb.audit(clean_frame())
+    out = tb.export(rep, tmp_path / "r.json", fmt="json")
+    assert out.exists() and '"score"' in out.read_text()
+
+
+def test_export_rejects_unknown_format(tmp_path):
+    with pytest.raises(ValueError, match="unsupported format"):
+        tb.export(tb.audit(clean_frame()), tmp_path / "r.xyz", fmt="xyz")
+
+
+# ---------- cli column mapping ----------
+
+def test_cli_maps_common_aliases():
+    from tickbloom.cli import normalize_columns
+    df = pd.DataFrame({"Datetime": ["2024-07-01T14:00:00Z"], "Px": [5500.0], "Qty": [2]})
+    out = normalize_columns(df, verbose=False)
+    assert {"ts_event", "price", "size", "symbol"} <= set(out.columns)
+    assert out["symbol"].iloc[0] == "UNKNOWN"
+
+
+def test_cli_exits_on_unmappable_columns():
+    from tickbloom.cli import normalize_columns
+    with pytest.raises(SystemExit):
+        normalize_columns(pd.DataFrame({"foo": [1], "bar": [2]}), verbose=False)