What it does for you
A model card, a README claim or a release note gets repeated, and its source goes missing. Model Provenance Validator checks a small JSON envelope that says what the claim is about, where the source came from, when it was retrieved and what validation status you are willing to publish. A batch run turns every problem into an action item, and redacts credential-shaped strings and local paths from its own messages.
- A source before the claimSubject, source, references with retrieval dates, and a published validation status are all required.
- Closed vocabulariesSource kinds and validation statuses come from fixed lists, so a status like certified is refused.
- Batch to action listMalformed files are reported as invalid results, and the run still finishes with a complete list.
- Proof packet
--proof-packetwrites a proof-surface packet for the batch.
Source: README.md at 1da6150 (version 0.1.1)
Watch
No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output.
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. The panel uses the bundled example envelope and the repository's invalid test fixture. Every line is output from model-provenance-validator at commit 1da6150.
- 01
An envelope for one claim
The bundled example is about a README's release-readiness claim. It names the source and its kind, a reference with a locator and the date it was retrieved, and a validation status of
partialwith a note that a person still has to review it. - 02
Validate it
The validator checks the five required fields, the allowed values and every nested field. The example is valid and the command exits 0.
Source: src/model_provenance_validator/validator.py, src/model_provenance_validator/schema.json
- 03
Every problem, with its path
The invalid fixture has an empty subject, an unknown source kind, no references and an extra field inside validation. Each becomes one error with a JSON path, and the command exits 1.
Source: tests/fixtures/invalid.json
- 04
A status you may publish
The validation status is a closed set: verified, partial or unknown. Change the example's status to
certifiedand the envelope is refused. - 05
A batch becomes an action list, and a packet
Run both files with
--summaryand you get totals and one action item per invalid file.--proof-packetwrites a proof-surface packet whose claims and checks carry the counts. Pick each in the panel.Source: src/model_provenance_validator/cli.py, src/model_provenance_validator/packet.py
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Install
Install from PyPI and clone for the examples. Python 3.10 or newer.
$ python -m pip install model-provenance-validator $ git clone https://github.com/HarperZ9/model-provenance-validator && cd model-provenance-validatorFirst run: a valid envelope
Validate the bundled release envelope.
$ model-provenance-validator examples/envelopes/release.provenance.json examples/envelopes/release.provenance.json: validAn invalid envelope
Each problem is named.
$ model-provenance-validator tests/fixtures/invalid.json tests/fixtures/invalid.json: invalid $.subject: expected non-empty string $.source.kind: invalid value 'unknown-kind'; expected one of: official-doc, paper, release-note, local-fixture, other $.references: expected at least 1 item(s) $.validation.extra: unexpected fieldA proof packet
Write the result as a packet.
$ model-provenance-validator examples/envelopes/release.provenance.json --proof-packet "surface": "model provenance validation" "status": "ready" "claims": envelopes=1; valid=1, invalid=0; validation errors=0 "checks": [{"tool": "model-provenance-validator", "status": "pass", "summary": "valid=1, invalid=0, errors=0"}] "action_items": []
Output from model-provenance-validator at 1da6150 run from source; version 0.1.1 is the current PyPI release.
What it does not do
- It validates the envelope's shape and the hygiene of its own report. The claim the envelope is about stays uncertified.
- A valid envelope means the fields are present and well-formed. Whether the reference supports the claim needs a person.
- Redaction applies to the validator's messages. The envelope file you wrote is left as written.
Source: README.md at 1da6150, "Current status" and "Usage"
Check what stuck
Answer each one in your head before you open it.
What four problems does the invalid fixture have?
An empty subject, an unknown source kind, no references and an unexpected field inside validation.
Why is a status of certified refused?
The status is a closed set of verified, partial and unknown.
Does a valid envelope prove the claim is true?
No. It proves the claim carries a well-formed source record.