vahtian 0.1.0__tar.gz

vahtian-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: publish
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  id-token: write          # OIDC trusted publishing — no API token stored
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pipx run build
+      - uses: pypa/gh-action-pypi-publish@release/v1

vahtian-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/

vahtian-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: vahtian
+Version: 0.1.0
+Summary: Reproducible, provenance-first evidence tooling — freeze a corpus, verify it, keep a hash-chained audit trail. Human-first, auditable, local-first.
+Project-URL: Homepage, https://vahtian.com/
+Project-URL: Documentation, https://vahtian.com/agents/
+Project-URL: Source, https://github.com/heidihelena/vahtian
+Author: Heidi Helena Andersén
+License: Apache-2.0
+Keywords: audit trail,evidence synthesis,provenance,reproducibility,research integrity,systematic review
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# vahtian (Python)
+
+Reproducible, provenance-first evidence tooling. **Freeze** a record set into a
+content-hashed, provenance-stamped, date-locked corpus; **verify** reproducibility;
+keep a **hash-chained audit trail**. Stdlib-only.
+
+The same core and on-disk format exist in the R package **`vahtian`**, so a corpus
+frozen in Python verifies in R and vice versa.
+
+```python
+import vahtian
+corpus = vahtian.freeze(records, search_date="2026-06-23")
+corpus.save("frozen-corpus")          # frozen-corpus.jsonl + .manifest.json
+assert vahtian.verify(corpus)         # tamper-evident
+
+L = vahtian.Ledger()
+L.append("human:hha", "rate", {"record_id": "pmid:12345", "value": "supported"})
+L.append("ai:opus/pv1", "advise", {"record_id": "pmid:12345", "value": "supported"})
+assert L.verify()                     # retro-edits break the chain
+```
+
+`vahti` (Finnish) = sentinel / guard. Human-first. AI-second. Auditable. Apache-2.0.

vahtian-0.1.0/README.md

@@ -0,0 +1,22 @@
+# vahtian (Python)
+
+Reproducible, provenance-first evidence tooling. **Freeze** a record set into a
+content-hashed, provenance-stamped, date-locked corpus; **verify** reproducibility;
+keep a **hash-chained audit trail**. Stdlib-only.
+
+The same core and on-disk format exist in the R package **`vahtian`**, so a corpus
+frozen in Python verifies in R and vice versa.
+
+```python
+import vahtian
+corpus = vahtian.freeze(records, search_date="2026-06-23")
+corpus.save("frozen-corpus")          # frozen-corpus.jsonl + .manifest.json
+assert vahtian.verify(corpus)         # tamper-evident
+
+L = vahtian.Ledger()
+L.append("human:hha", "rate", {"record_id": "pmid:12345", "value": "supported"})
+L.append("ai:opus/pv1", "advise", {"record_id": "pmid:12345", "value": "supported"})
+assert L.verify()                     # retro-edits break the chain
+```
+
+`vahti` (Finnish) = sentinel / guard. Human-first. AI-second. Auditable. Apache-2.0.

vahtian-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vahtian"
+version = "0.1.0"
+description = "Reproducible, provenance-first evidence tooling — freeze a corpus, verify it, keep a hash-chained audit trail. Human-first, auditable, local-first."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Heidi Helena Andersén" }]
+keywords = ["research integrity", "systematic review", "provenance", "reproducibility", "evidence synthesis", "audit trail"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = []   # stdlib only — re-runnable anywhere
+
+[project.urls]
+Homepage = "https://vahtian.com/"
+Documentation = "https://vahtian.com/agents/"
+Source = "https://github.com/heidihelena/vahtian"
+
+[project.scripts]
+vahtian = "vahtian.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vahtian"]

vahtian-0.1.0/src/vahtian/__init__.py

@@ -0,0 +1,19 @@
+"""vahtian — reproducible, provenance-first evidence tooling.
+
+Freeze a record set into a content-hashed, provenance-stamped, date-locked
+corpus; verify reproducibility; keep a hash-chained audit trail. The same core
+and on-disk format exist in the R package `vahtian`, so artifacts interoperate.
+
+Human-first. AI-second. Auditable. Apache-2.0.
+"""
+from .provenance import Corpus, freeze, load, content_hash, record_id, SPEC_VERSION
+from .audit import Ledger
+
+__version__ = "0.1.0"
+__all__ = ["Corpus", "freeze", "load", "verify", "content_hash", "record_id",
+           "Ledger", "SPEC_VERSION", "__version__"]
+
+
+def verify(corpus: "Corpus") -> bool:
+    """Convenience: vahtian.verify(corpus) == corpus.verify()."""
+    return corpus.verify()

vahtian-0.1.0/src/vahtian/audit.py

@@ -0,0 +1,48 @@
+"""Hash-chained, tamper-evident audit ledger — who did what, in order.
+
+Each entry hashes the previous entry's hash, so any retro-edit or deletion breaks
+the chain and verify() catches it. Shared format with the R package.
+"""
+from __future__ import annotations
+import json, hashlib
+from datetime import datetime, timezone
+
+GENESIS = "sha256:" + "0" * 64
+
+
+def _canonical(obj) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _entry_hash(prev_hash: str, body: dict) -> str:
+    h = hashlib.sha256()
+    h.update(prev_hash.encode("utf-8"))
+    h.update(_canonical(body).encode("utf-8"))
+    return "sha256:" + h.hexdigest()
+
+
+class Ledger:
+    def __init__(self):
+        self.entries: list[dict] = []
+
+    def append(self, actor: str, action: str, payload: dict | None = None, *, ts: str | None = None) -> dict:
+        prev = self.entries[-1]["entry_hash"] if self.entries else GENESIS
+        body = {"seq": len(self.entries), "ts": ts or datetime.now(timezone.utc).isoformat(),
+                "actor": actor, "action": action, "payload": payload or {}, "prev_hash": prev}
+        entry = {**body, "entry_hash": _entry_hash(prev, body)}
+        self.entries.append(entry)
+        return entry
+
+    def verify(self) -> bool:
+        prev = GENESIS
+        for e in self.entries:
+            body = {k: e[k] for k in ("seq", "ts", "actor", "action", "payload", "prev_hash")}
+            if e["prev_hash"] != prev or _entry_hash(prev, body) != e["entry_hash"]:
+                return False
+            prev = e["entry_hash"]
+        return True
+
+    def save(self, path: str) -> None:
+        with open(path, "w", encoding="utf-8") as f:
+            for e in self.entries:
+                f.write(_canonical(e) + "\n")

vahtian-0.1.0/src/vahtian/cli.py

@@ -0,0 +1,16 @@
+"""`vahtian` CLI — verify a frozen corpus or an audit ledger."""
+import sys
+from . import load, __version__
+from .audit import Ledger
+
+def main(argv=None):
+    argv = argv if argv is not None else sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        print("vahtian", __version__, "\n  vahtian verify <corpus-prefix>   # check a frozen corpus is untampered")
+        return 0
+    if argv[0] == "verify" and len(argv) > 1:
+        c = load(argv[1])
+        ok = c.verify()
+        print(("OK  " if ok else "FAIL ") + f"{len(c.records)} records · {c.search_date} · {c.content_hash}")
+        return 0 if ok else 1
+    print("unknown command:", argv[0]); return 2

vahtian-0.1.0/src/vahtian/provenance.py

@@ -0,0 +1,100 @@
+"""Frozen, provenance-stamped evidence corpus — the Vahtian reproducibility core.
+
+A corpus is a deduped set of records, each carrying per-source provenance and a
+locked search date, summarised by a content hash. Re-running the search and
+re-freezing must reproduce the same hash; verify() proves it (tamper-evident).
+
+The on-disk format (frozen-corpus.jsonl + .manifest.json) is shared byte-for-byte
+with the R package, so a corpus frozen in Python verifies in R and vice versa.
+"""
+from __future__ import annotations
+import json, hashlib
+from dataclasses import dataclass, field, asdict
+from datetime import date, datetime, timezone
+
+SPEC_VERSION = "vahtian-corpus/1"
+
+
+def record_id(rec: dict) -> str:
+    """Stable identity: PMID > DOI > title-hash. Matches the R implementation."""
+    if rec.get("pmid"):
+        return f"pmid:{str(rec['pmid']).strip()}"
+    if rec.get("doi"):
+        return "doi:" + str(rec["doi"]).strip().lower()
+    title = (rec.get("title") or "").strip().lower()
+    return "title:" + hashlib.sha256(title.encode("utf-8")).hexdigest()[:16]
+
+
+def _canonical(obj) -> str:
+    # Deterministic serialisation: sorted keys, no whitespace, UTF-8.
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def content_hash(records: list[dict]) -> str:
+    """sha256 over records sorted by record_id — order-independent, reproducible."""
+    ordered = sorted(records, key=record_id)
+    h = hashlib.sha256()
+    for r in ordered:
+        h.update(_canonical(r).encode("utf-8"))
+        h.update(b"\n")
+    return "sha256:" + h.hexdigest()
+
+
+@dataclass
+class Corpus:
+    records: list[dict]
+    search_date: str
+    content_hash: str
+    created: str = field(default="")
+    spec: str = SPEC_VERSION
+
+    def verify(self) -> bool:
+        """True iff the stored content_hash still matches the records (untampered)."""
+        return content_hash(self.records) == self.content_hash
+
+    def manifest(self) -> dict:
+        return {"spec": self.spec, "n_records": len(self.records),
+                "search_date": self.search_date, "content_hash": self.content_hash,
+                "created": self.created}
+
+    def save(self, path_prefix: str) -> None:
+        with open(path_prefix + ".jsonl", "w", encoding="utf-8") as f:
+            for r in sorted(self.records, key=record_id):
+                f.write(_canonical(r) + "\n")
+        with open(path_prefix + ".manifest.json", "w", encoding="utf-8") as f:
+            f.write(json.dumps(self.manifest(), indent=2))
+
+
+def freeze(records: list[dict], search_date: str | None = None, *, now: str | None = None) -> Corpus:
+    """Dedupe by record_id, lock the search date, compute the content hash."""
+    by_id: dict[str, dict] = {}
+    for rec in records:
+        rid = record_id(rec)
+        merged = dict(rec); merged["record_id"] = rid
+        if rid in by_id:  # merge provenance across sources
+            prov = by_id[rid].get("provenance", []) + merged.get("provenance", [])
+            merged = {**by_id[rid], **merged, "provenance": prov}
+        by_id[rid] = merged
+    records = list(by_id.values())
+    for r in records:                       # canonicalise provenance order so the hash
+        prov = r.get("provenance")          # is independent of source arrival order
+        if isinstance(prov, list):
+            r["provenance"] = sorted(prov, key=_canonical)
+    sd = search_date or date.today().isoformat()
+    return Corpus(records=records, search_date=sd,
+                  content_hash=content_hash(records),
+                  created=now or datetime.now(timezone.utc).isoformat())
+
+
+def load(path_prefix: str) -> Corpus:
+    records = []
+    with open(path_prefix + ".jsonl", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                records.append(json.loads(line))
+    with open(path_prefix + ".manifest.json", encoding="utf-8") as f:
+        m = json.load(f)
+    return Corpus(records=records, search_date=m["search_date"],
+                  content_hash=m["content_hash"], created=m.get("created", ""),
+                  spec=m.get("spec", SPEC_VERSION))

vahtian-0.1.0/tests/test_core.py

@@ -0,0 +1,44 @@
+import vahtian
+
+# The cross-language parity gate: the R package `vahtian` asserts this SAME literal.
+# If either canonical serialiser drifts, one of the two CIs goes red.
+GOLDEN = "sha256:50ca741a72e7058870d0ca7594b0c37faa7183472fcb1752b7a6c5abe23cafd1"
+
+def test_golden_cross_language_hash():
+    recs = [
+        {"pmid": "12345", "title": "PD-L1 AI scoring agrees with pathologists",
+         "provenance": [{"source": "pubmed", "retrieved": "2026-06-23"}]},
+        {"doi": "10.1/x", "title": "A second study",
+         "provenance": [{"source": "openalex", "retrieved": "2026-06-23"}]},
+        {"pmid": "12345", "title": "PD-L1 AI scoring agrees with pathologists",
+         "provenance": [{"source": "europepmc", "retrieved": "2026-06-23"}]},
+    ]
+    c = vahtian.freeze(recs, search_date="2026-06-23")
+    assert len(c.records) == 2
+    assert c.content_hash == GOLDEN
+
+def test_dedupe_and_reproducible():
+    recs = [
+        {"pmid": "1", "title": "A", "provenance": [{"source": "pubmed"}]},
+        {"pmid": "1", "title": "A", "provenance": [{"source": "europepmc"}]},
+        {"doi": "10.1/x", "title": "B", "provenance": [{"source": "openalex"}]},
+    ]
+    c1 = vahtian.freeze(recs, search_date="2026-06-23", now="t")
+    c2 = vahtian.freeze(list(reversed(recs)), search_date="2026-06-23", now="t2")
+    assert len(c1.records) == 2
+    assert c1.content_hash == c2.content_hash   # order-independent
+    assert c1.verify()
+
+def test_tamper_detection():
+    c = vahtian.freeze([{"pmid": "1", "title": "A"}], search_date="2026-06-23")
+    assert c.verify()
+    c.records[0]["title"] = "tampered"
+    assert not c.verify()
+
+def test_audit_chain():
+    L = vahtian.Ledger()
+    L.append("human", "rate", {"v": "supported"}, ts="t1")
+    L.append("ai", "advise", {"v": "supported"}, ts="t2")
+    assert L.verify()
+    L.entries[0]["payload"]["v"] = "x"
+    assert not L.verify()