httk.core.provenance

Stdlib-only OPTIMADE-aligned calculation provenance records.

Runs carry the internal, unprefixed entry-type name runs; the provider prefix (_httk_runs) is applied by the single wire transform at the serving edge, not stored here. 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. entry_type is the INTERNAL (unprefixed) entry-type name and entry_id is the raw store-minted id of an entry in the SAME database; cross-provider linking is not supported. Edges are servable as OPTIMADE semantic relationships — the forward direction under the owning field’s StrongLink relationship key, the reverse direction derived at serving time — so the composite (entry_type, entry_id) index exists for those reverse lookups.

Parameters:

  • label – The relationship label.

  • entry_type – The related entry type name (internal, unprefixed).

  • entry_id – The related entry identifier (raw store-minted id, same database).

label: str
entry_type: str
entry_id: str
classmethod from_obj(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: each edge names an entry by its INTERNAL (unprefixed) entry_type and raw store-minted entry_id in the SAME database (cross-provider linking is not supported). Labels are unique independently on each of inputs, artifacts, and outputs. The three sides carry StrongLink markers declaring their internal (unprefixed) relationship keys, so each side is servable as an OPTIMADE semantic relationship in both directions (forward under the marker’s relationship key, reverse derived at serving time); the provider prefix is applied at the serving edge, not here.

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.

  • source_id – The run’s identifier in the system that executed it; part of the content identity so re-collecting the same job deduplicates to one row while distinct jobs stay distinct.

  • id – The human-readable entry id shared by all revisions; minted by the store when None.

  • immutable_id – The per-revision immutable id; minted by the store when None.

  • last_modified – The optional timezone-aware metadata timestamp.

workflow_declaration_uri: str | None = None
inputs: Annotated[tuple[RunEdge, Ellipsis], StrongLink('has_input', reverse='is_input', role='input')] = ()
artifacts: Annotated[tuple[RunEdge, Ellipsis], StrongLink('has_artifact', reverse='is_artifact', role='artifact')] = ()
outputs: Annotated[tuple[RunEdge, Ellipsis], StrongLink('has_output', reverse='is_output', role='output')] = ()
source_id: Annotated[str | None, Indexed()] = None
id: Annotated[str | None, IdentitySkip(), Indexed()] = None
immutable_id: Annotated[str | None, IdentitySkip(), Unique()] = None
last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None
property type: str

Return the internal (unprefixed) entry type name.

classmethod from_obj(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

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 from_obj(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 = 'runs'
definition_id = 'https://schemas.httk.org/defs/v0.1/entrytypes/runs'