policyengine 3.4.3__tar.gz → 3.4.4__tar.gz

{policyengine-3.4.3 → policyengine-3.4.4}/.github/workflows/push.yaml

@@ -81,10 +81,8 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 18.x
-      - name: Install MyST
-        run: npm install -g mystmd
       - name: Build HTML Assets
-        run: cd docs && myst build --html
+        run: make docs
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

{policyengine-3.4.3 → policyengine-3.4.4}/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [3.4.4] - 2026-04-13
+
+### Changed
+
+- Add TRACE TRO export helpers for certified runtime bundles and expose them through `policyengine.core`.
+
+
 ## [3.4.3] - 2026-04-13
 
 ### Fixed

{policyengine-3.4.3 → policyengine-3.4.4}/Makefile

@@ -1,9 +1,15 @@
-.PHONY: docs
+.PHONY: docs docs-serve
+
+MYSTMD_VERSION ?= 1.8.3
+MYST_CMD = npx --yes mystmd@$(MYSTMD_VERSION)
 
 all: build-package
 
 docs:
-	cd docs && jupyter book start
+	cd docs && $(MYST_CMD) build --html
+
+docs-serve:
+	cd docs && $(MYST_CMD) start
 
 install:
 	uv pip install -e .[dev]
@@ -27,4 +33,4 @@ build-package:
 	python -m build
 
 test:
-	pytest tests --cov=policyengine --cov-report=term-missing
+	pytest tests --cov=policyengine --cov-report=term-missing

{policyengine-3.4.3 → policyengine-3.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 3.4.3
+Version: 3.4.4
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -788,7 +788,8 @@ uv pip install -e .[dev]        # install with dev dependencies (pytest, ruff, m
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # build Jupyter Book documentation
+make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```
 

{policyengine-3.4.3 → policyengine-3.4.4}/README.md

@@ -86,7 +86,8 @@ uv pip install -e .[dev]        # install with dev dependencies (pytest, ruff, m
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # build Jupyter Book documentation
+make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```
 

{policyengine-3.4.3 → policyengine-3.4.4}/docs/dev.md

@@ -23,7 +23,8 @@ dependencies used in CI (pytest, ruff, mypy, towncrier).
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # run the MyST docs build used in CI via npx
+make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```
 

{policyengine-3.4.3 → policyengine-3.4.4}/docs/release-bundles.md

@@ -186,6 +186,55 @@ Notes:
 - apps and APIs should surface this bundle, not only country package versions
 - a bundle may reuse a previously staged data artifact if compatibility is explicitly certified
 
+## TRACE export
+
+The internal build manifest and certified runtime bundle remain the operational source of
+truth.
+
+TRACE sits on top of those manifests as a standards-based export layer.
+
+### What gets exported
+
+Country `*-data` repos should emit a `trace.tro.jsonld` file for each published data
+release. That TRO should cover:
+
+- the release manifest itself
+- each published artifact hash listed in the release manifest
+- the build-time model provenance recorded in the release manifest
+
+`policyengine.py` should emit a separate certified-bundle TRO. That TRO should cover:
+
+- the bundled country release manifest shipped in `policyengine.py`
+- the country data release manifest resolved for the certified data package version
+- the certified dataset artifact hash
+- the certification basis used to allow runtime reuse
+
+### What TRACE does not replace
+
+TRACE is not the source of truth for compatibility policy.
+
+In particular, TRACE does not decide:
+
+- whether a new model version can safely reuse an existing data artifact
+- how `data_build_fingerprint` is computed
+- which staged artifact becomes a supported runtime default
+
+Those decisions still belong to the country data build manifest and the
+`policyengine.py` certified runtime bundle.
+
+### Why we still want it
+
+TRACE adds three things our internal manifests do not provide by themselves:
+
+- a standard declaration format for provenance exchange
+- a composition fingerprint over the exact artifacts in scope
+- a better external surface for papers, audits, and reproducibility reviews
+
+That is why the recommended design is:
+
+- internal manifests for build/certification control
+- generated TRACE TROs for standards-based export
+
 ## Compatibility rule
 
 The architecture should avoid forcing a new data build for every harmless country model release.

{policyengine-3.4.3 → policyengine-3.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "policyengine"
-version = "3.4.3"
+version = "3.4.4"
 description = "A package to conduct policy analysis using PolicyEngine tax-benefit models."
 readme = "README.md"
 authors = [

{policyengine-3.4.3 → policyengine-3.4.4}/src/policyengine/core/__init__.py

@@ -36,6 +36,13 @@ from .tax_benefit_model import TaxBenefitModel as TaxBenefitModel
 from .tax_benefit_model_version import (
     TaxBenefitModelVersion as TaxBenefitModelVersion,
 )
+from .trace_tro import (
+    build_trace_tro_from_release_bundle as build_trace_tro_from_release_bundle,
+)
+from .trace_tro import (
+    compute_trace_composition_fingerprint as compute_trace_composition_fingerprint,
+)
+from .trace_tro import serialize_trace_tro as serialize_trace_tro
 from .variable import Variable as Variable
 
 # Rebuild models to resolve forward references

{policyengine-3.4.3 → policyengine-3.4.4}/src/policyengine/core/tax_benefit_model_version.py

@@ -4,8 +4,14 @@ from uuid import uuid4
 
 from pydantic import BaseModel, Field
 
-from .release_manifest import CountryReleaseManifest, DataCertification, PackageVersion
+from .release_manifest import (
+    CountryReleaseManifest,
+    DataCertification,
+    PackageVersion,
+    get_data_release_manifest,
+)
 from .tax_benefit_model import TaxBenefitModel
+from .trace_tro import build_trace_tro_from_release_bundle
 
 if TYPE_CHECKING:
     from .parameter import Parameter
@@ -201,6 +207,22 @@ class TaxBenefitModelVersion(BaseModel):
             ),
         }
 
+    @property
+    def trace_tro(self) -> dict:
+        if self.release_manifest is None:
+            raise ValueError(
+                "TRACE TRO export requires a bundled country release manifest."
+            )
+
+        data_release_manifest = get_data_release_manifest(
+            self.release_manifest.country_id
+        )
+        return build_trace_tro_from_release_bundle(
+            self.release_manifest,
+            data_release_manifest,
+            certification=self.data_certification,
+        )
+
     def __repr__(self) -> str:
         # Give the id and version, and the number of variables, parameters, parameter nodes, parameter values
         return f"<TaxBenefitModelVersion id={self.id} variables={len(self.variables)} parameters={len(self.parameters)} parameter_nodes={len(self.parameter_nodes)} parameter_values={len(self.parameter_values)}>"

policyengine-3.4.4/src/policyengine/core/trace_tro.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable, Mapping
+
+from .release_manifest import (
+    CountryReleaseManifest,
+    DataCertification,
+    DataReleaseManifest,
+)
+
+TRACE_TROV_VERSION = "0.1"
+TRACE_CONTEXT = [
+    {
+        "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+        "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+        "trov": "https://w3id.org/trace/trov/0.1#",
+        "schema": "https://schema.org/",
+    }
+]
+
+
+def _hash_object(value: str) -> dict[str, str]:
+    return {
+        "trov:hashAlgorithm": "sha256",
+        "trov:hashValue": value,
+    }
+
+
+def _artifact_mime_type(path_or_uri: str) -> str | None:
+    suffix = path_or_uri.rsplit(".", 1)[-1].lower() if "." in path_or_uri else ""
+    return {
+        "h5": "application/x-hdf5",
+        "json": "application/json",
+        "jsonld": "application/ld+json",
+    }.get(suffix)
+
+
+def _canonical_json_bytes(value: Mapping) -> bytes:
+    return (json.dumps(value, indent=2, sort_keys=True) + "\n").encode("utf-8")
+
+
+def compute_trace_composition_fingerprint(
+    artifact_hashes: Iterable[str],
+) -> str:
+    digest = hashlib.sha256()
+    digest.update("".join(sorted(artifact_hashes)).encode("utf-8"))
+    return digest.hexdigest()
+
+
+def build_trace_tro_from_release_bundle(
+    country_manifest: CountryReleaseManifest,
+    data_release_manifest: DataReleaseManifest,
+    *,
+    certification: DataCertification | None = None,
+    bundle_manifest_path: str | None = None,
+    data_release_manifest_path: str | None = None,
+) -> dict:
+    certified_artifact = country_manifest.certified_data_artifact
+    if certified_artifact is None:
+        raise ValueError(
+            "Country release manifest does not define a certified artifact."
+        )
+
+    dataset_artifact = data_release_manifest.artifacts.get(certified_artifact.dataset)
+    if dataset_artifact is None:
+        raise ValueError(
+            "Data release manifest does not include the certified dataset "
+            f"'{certified_artifact.dataset}'."
+        )
+    if dataset_artifact.sha256 is None:
+        raise ValueError(
+            "Data release manifest does not include a SHA256 for the certified dataset "
+            f"'{certified_artifact.dataset}'."
+        )
+
+    effective_certification = certification or country_manifest.certification
+    bundle_manifest_location = (
+        bundle_manifest_path
+        or f"data/release_manifests/{country_manifest.country_id}.json"
+    )
+    data_manifest_location = data_release_manifest_path or (
+        "https://huggingface.co/"
+        f"{country_manifest.data_package.repo_id}/resolve/"
+        f"{country_manifest.data_package.version}/"
+        f"{country_manifest.data_package.release_manifest_path}"
+    )
+
+    bundle_manifest_payload = country_manifest.model_dump(mode="json")
+    data_release_payload = data_release_manifest.model_dump(mode="json")
+    bundle_manifest_hash = hashlib.sha256(
+        _canonical_json_bytes(bundle_manifest_payload)
+    ).hexdigest()
+    data_release_manifest_hash = hashlib.sha256(
+        _canonical_json_bytes(data_release_payload)
+    ).hexdigest()
+
+    artifact_specs = [
+        {
+            "hash": bundle_manifest_hash,
+            "location": bundle_manifest_location,
+            "mime_type": "application/json",
+        },
+        {
+            "hash": data_release_manifest_hash,
+            "location": data_manifest_location,
+            "mime_type": "application/json",
+        },
+        {
+            "hash": dataset_artifact.sha256,
+            "location": certified_artifact.uri,
+            "mime_type": _artifact_mime_type(certified_artifact.uri),
+        },
+    ]
+
+    composition_artifacts = []
+    arrangement_locations = []
+    artifact_hashes = []
+
+    for index, artifact in enumerate(artifact_specs):
+        artifact_id = f"composition/1/artifact/{index}"
+        artifact_hashes.append(artifact["hash"])
+        artifact_entry = {
+            "@id": artifact_id,
+            "@type": "trov:ResearchArtifact",
+            "trov:hash": _hash_object(artifact["hash"]),
+        }
+        if artifact["mime_type"] is not None:
+            artifact_entry["trov:mimeType"] = artifact["mime_type"]
+        composition_artifacts.append(artifact_entry)
+        arrangement_locations.append(
+            {
+                "@id": f"arrangement/0/location/{index}",
+                "@type": "trov:ArtifactLocation",
+                "trov:artifact": {"@id": artifact_id},
+                "trov:path": artifact["location"],
+            }
+        )
+
+    certification_description = ""
+    if effective_certification is not None:
+        certification_description = (
+            f" Certified for runtime model version "
+            f"{effective_certification.certified_for_model_version} via "
+            f"{effective_certification.compatibility_basis}."
+        )
+        if effective_certification.built_with_model_version is not None:
+            certification_description += (
+                f" Built with {country_manifest.model_package.name} "
+                f"{effective_certification.built_with_model_version}."
+            )
+        if effective_certification.data_build_fingerprint is not None:
+            certification_description += (
+                f" Data-build fingerprint: "
+                f"{effective_certification.data_build_fingerprint}."
+            )
+
+    created_at = country_manifest.published_at or (
+        data_release_manifest.build.built_at
+        if data_release_manifest.build is not None
+        else None
+    )
+    build_id = (
+        effective_certification.data_build_id
+        if effective_certification is not None
+        else (
+            certified_artifact.build_id
+            or f"{country_manifest.data_package.name}-{country_manifest.data_package.version}"
+        )
+    )
+
+    return {
+        "@context": TRACE_CONTEXT,
+        "@graph": [
+            {
+                "@id": "tro",
+                "@type": ["trov:TransparentResearchObject", "schema:CreativeWork"],
+                "trov:vocabularyVersion": TRACE_TROV_VERSION,
+                "schema:creator": country_manifest.policyengine_version,
+                "schema:name": (
+                    f"policyengine {country_manifest.country_id} certified bundle TRO"
+                ),
+                "schema:description": (
+                    f"TRACE TRO for certified runtime bundle "
+                    f"{country_manifest.bundle_id or country_manifest.country_id} "
+                    f"covering the bundled country release manifest, the country data "
+                    f"release manifest, and the certified dataset artifact."
+                    f"{certification_description}"
+                ),
+                "schema:dateCreated": created_at,
+                "trov:wasAssembledBy": {
+                    "@id": "trs",
+                    "@type": ["trov:TrustedResearchSystem", "schema:Organization"],
+                    "schema:name": "PolicyEngine certified release bundle pipeline",
+                    "schema:description": (
+                        "PolicyEngine certification workflow for runtime bundles that "
+                        "pin a country model version, a country data release, and a "
+                        "specific dataset artifact."
+                    ),
+                },
+                "trov:createdWith": {
+                    "@type": "schema:SoftwareApplication",
+                    "schema:name": "policyengine",
+                    "schema:softwareVersion": country_manifest.policyengine_version,
+                },
+                "trov:hasComposition": {
+                    "@id": "composition/1",
+                    "@type": "trov:ArtifactComposition",
+                    "trov:hasFingerprint": {
+                        "@id": "fingerprint",
+                        "@type": "trov:CompositionFingerprint",
+                        "trov:hash": _hash_object(
+                            compute_trace_composition_fingerprint(artifact_hashes)
+                        ),
+                    },
+                    "trov:hasArtifact": composition_artifacts,
+                },
+                "trov:hasArrangement": [
+                    {
+                        "@id": "arrangement/0",
+                        "@type": "trov:ArtifactArrangement",
+                        "rdfs:comment": (
+                            f"Certified arrangement for bundle "
+                            f"{country_manifest.bundle_id or country_manifest.country_id}."
+                        ),
+                        "trov:hasArtifactLocation": arrangement_locations,
+                    }
+                ],
+                "trov:hasPerformance": [
+                    {
+                        "@id": "trp/0",
+                        "@type": "trov:TrustedResearchPerformance",
+                        "rdfs:comment": (
+                            f"Certification of build {build_id} for "
+                            f"{country_manifest.model_package.name} "
+                            f"{country_manifest.model_package.version}."
+                        ),
+                        "trov:wasConductedBy": {"@id": "trs"},
+                        "trov:startedAtTime": (
+                            data_release_manifest.build.built_at
+                            if data_release_manifest.build is not None
+                            else created_at
+                        ),
+                        "trov:endedAtTime": created_at,
+                        "trov:contributedToArrangement": {
+                            "@id": "trp/0/binding/0",
+                            "@type": "trov:ArrangementBinding",
+                            "trov:arrangement": {"@id": "arrangement/0"},
+                        },
+                    }
+                ],
+            }
+        ],
+    }
+
+
+def serialize_trace_tro(tro: Mapping) -> bytes:
+    return (json.dumps(tro, indent=2, sort_keys=True) + "\n").encode("utf-8")

{policyengine-3.4.3 → policyengine-3.4.4}/src/policyengine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 3.4.3
+Version: 3.4.4
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -788,7 +788,8 @@ uv pip install -e .[dev]        # install with dev dependencies (pytest, ruff, m
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # build Jupyter Book documentation
+make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```
 

{policyengine-3.4.3 → policyengine-3.4.4}/src/policyengine.egg-info/SOURCES.txt

@@ -65,6 +65,7 @@ src/policyengine/core/scoping_strategy.py
 src/policyengine/core/simulation.py
 src/policyengine/core/tax_benefit_model.py
 src/policyengine/core/tax_benefit_model_version.py
+src/policyengine/core/trace_tro.py
 src/policyengine/core/variable.py
 src/policyengine/countries/__init__.py
 src/policyengine/countries/uk/__init__.py