Configuration

makeprov reads settings from a process-wide configuration instance stored on makeprov.ProvenanceConfig and allows runtime overrides via the command line. This page summarizes the available options and demonstrates common configurations.

Available options

Field	Description
`base_iri`	Default IRI used to construct provenance identifiers.
`prov_dir`	Directory where provenance documents are written when no explicit path is set.
`prov_path`	Explicit path to the provenance document; overrides `prov_dir`.
`force`	When true, run rules regardless of timestamp checks.
`merge`	When true, collect provenance in a workflow-level buffer and emit a single document at the end of the run.
`stream`	Append each finished activity to a recovery `.jsonl`; if `merge=true`, atomically write the final merged document and remove the `.jsonl` on success.
`record_environment`	Record retrospective environment evidence: distributions this run actually imported (pinned to exact versions), plus a citation of any lockfile found. See Environment evidence.
`dry_run`	Log actions without running rule bodies.
`out_fmt`	Output format: `"json"` for JSON-LD or `"trig"` for RDF TriG.
`context`	Embed JSON-LD context in output documents.
`context_url`	URL to reference in `@context` when `context` is `false`.

Applying overrides

Supply one or more --conf flags to makeprov.config.main(). Each flag accepts either a TOML snippet or an @-prefixed path to a TOML file.

python -m makeprov --conf '{prov_dir="artifacts/prov"}' my_rule
python -m makeprov --conf @config/provenance.toml --conf '{out_fmt="trig"}' my_rule

You can also update the configuration programmatically:

from makeprov import ProvenanceConfig

cfg = ProvenanceConfig.get()
cfg.apply('{force=true, out_fmt="trig"}')
ProvenanceConfig.set(cfg.clone_with(prov_dir="artifacts/prov"))

Merge semantics

When merge is true (the default), makeprov opens a single provenance buffer for the workflow run and appends provenance from every rule to that buffer. The buffer is flushed once at the end of the run (by the CLI entrypoint or the top-level call to makeprov.core.build()), ensuring that nested rules never emit their own documents. Any per-rule prov_path is ignored while a workflow buffer is active; set merge=false, stream=false to force a rule to write its own provenance file immediately.

Recovery streaming

Set ProvenanceConfig(stream=True) to write one independently contextualized JSON-LD document per JSONL line. An initial parent activity record preserves its ID and start time after interruption. Child records link back to that ID; the parent completion record is appended last. On successful completion with merge=True (the default), makeprov atomically replaces the merged .json or .trig output and deletes the .jsonl. If execution or final writing fails, the .jsonl remains. Set merge=False to retain JSONL as the only output.

JSONL is makeprov’s recovery format, not a single standards-compliant JSON-LD document. An existing .jsonl is never overwritten: move it before rerunning. Streaming records are flushed on close, without an fsync durability guarantee. Recovery of provenance does not automatically resume the computation.

Context isolation

The JSON-LD context in makeprov is treated as an immutable template. Each call to makeprov.prov.Prov.create copies the common context and applies repository-specific defaults (such as @base and blob IRIs discovered from git) to the copy instead of mutating shared globals. This guarantees that one workflow run cannot leak context updates into another. Use makeprov.ProvenanceConfig to set a base_iri for identifiers without worrying about cross-run side effects.

Isolating state with sessions

Rule registries and provenance buffers live in a :class:~makeprov.core.Session object. makeprov creates a default session for convenience, but you can instantiate your own to keep multiple runs from sharing state:

from makeprov import OutPath, build, new_session, rule

session = new_session()

@rule(session=session)
def generate(out: OutPath = OutPath("data/output.txt")):
    out.write_text("content")

build("data/output.txt", session=session)

Pass the same session to CLI entrypoints via makeprov.config.main() to ensure commands and buffers remain isolated.

Context handling

Set context=true to embed the JSON-LD context inline from src/makeprov/context.jsonld.
When context=false, the @context field is set to context_url (default: https://w3id.org/makeprov/context), so you can pin consumers to a specific published version without hard-coding it in code. Override context_url in a TOML snippet or file if you host the context elsewhere.

Inspecting dependency graphs

Two CLI flags help you explore build order without executing any rules:

--explain TARGET logs which rule will satisfy a target.
--to-dot TARGET prints a Graphviz DOT representation of the dependency graph.

Example TOML file

base_iri = "https://example.org/makeprov"
prov_dir = "build/prov"
out_fmt = "trig"
merge = true