httk.core.provenance

Stdlib-only OPTIMADE-aligned calculation provenance records.

Runs are served as provider-prefixed _httk_runs entries. Their has_input/has_artifact/has_output relationships are represented by loose labeled references rather than object references: inputs are consumed, artifacts are created, and outputs are returned. The single-creator rule for artifacts is a serving concern and is not enforced on an individual record. The definition identity remains the unprefixed RUNS_DEFINITION_ID IRI.

Attributes

RUNS_DEFINITION_ID

Classes

RunEdge	Store one loose labeled reference from a run to another entry.
Run	One workflow execution with loose provenance edges.
ProductLink	A curation has_product/is_product edge between data entries.
RunEntry	Logical entry family for served Run records.

Module Contents

httk.core.provenance.RUNS_DEFINITION_ID = 'https://schemas.httk.org/defs/v0.1/entrytypes/runs'

class httk.core.provenance.RunEdge

Store one loose labeled reference from a run to another entry.

Edges deliberately keep the related entry’s type and identifier as strings rather than object references, so a run can refer to entries served by another provider.

Parameters:

• label – The relationship label.

• entry_type – The related entry type name.

• entry_id – The related entry identifier.

label: str

entry_type: str

entry_id: str

classmethod create(obj)

Coerce a mapping or existing edge into a RunEdge.

Parameters:

obj (RunEdge | Mapping[str, Any]) – A run edge instance or field mapping.

Returns:

The existing or newly constructed run edge.

Raises:

• TypeError – If obj is neither a run edge nor a mapping.

• ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.provenance.Run

One workflow execution with loose provenance edges.

inputs are has_input edges to consumed entries, artifacts are has_artifact edges to created entries, and outputs are has_output edges to returned entries. Artifact single-creator exclusivity across runs is documented here, not enforced per record.

Every invariant is cheap and total, so there is deliberately no __httk_validate__ hook.

Edges remain loose string triples by design, never object references. Labels are unique independently on each of inputs, artifacts, and outputs.

Parameters:

• workflow_declaration_uri – The workflow declaration IRI, if declared.

• inputs – The labeled entries consumed by the run.

• artifacts – The labeled entries created by the run.

• outputs – The labeled entries returned by the run.

• immutable_id – An optional provider-specific immutable identifier.

• last_modified – The optional timezone-aware metadata timestamp.

workflow_declaration_uri: str | None = None

inputs: tuple[RunEdge, Ellipsis] = ()

artifacts: tuple[RunEdge, Ellipsis] = ()

outputs: tuple[RunEdge, Ellipsis] = ()

immutable_id: Annotated[str | None, IdentitySkip()] = None

last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None

property type: str

Return the served entry type name.

property id: str

Return the content identity of this run.

classmethod create(obj)

Coerce a mapping or existing run into a Run.

Parameters:

obj (Run | Mapping[str, Any]) – A run instance or field mapping.

Returns:

The existing or newly constructed run.

Raises:

• TypeError – If obj is neither a run nor a mapping.

• ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.provenance.ProductLink

A curation has_product/is_product edge between data entries.

A label is unique per source entry across links; that constraint is enforced at the serving projection rather than on each record.

Parameters:

• source_type – The source entry type name.

• source_id – The source entry identifier.

• target_type – The target entry type name.

• target_id – The target entry identifier.

• label – The relationship label, unique per source entry at serving time.

• workflow_declaration_uri – The workflow declaration IRI, if declared.

source_type: str

source_id: str

target_type: str

target_id: str

label: str

workflow_declaration_uri: str | None = None

classmethod create(obj)

Coerce a mapping or existing link into a ProductLink.

Parameters:

obj (ProductLink | Mapping[str, Any]) – A product-link instance or field mapping.

Returns:

The existing or newly constructed product link.

Raises:

• TypeError – If obj is neither a product link nor a mapping.

• ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.provenance.RunEntry

Logical entry family for served Run records.

This family is not itself storable; store a Run directly.

type = '_httk_runs'

definition_id = 'https://schemas.httk.org/defs/v0.1/entrytypes/runs'