Provium core API reference

The public API exported by provium.

provium

Core functionality for the Provium platform.

__version__ = version('provium') module-attribute

CLI_PLUGIN_API_VERSION = 1 module-attribute

The CLI plugin API version supported by this Provium release.

CLI_PLUGIN_ENTRY_POINT_GROUP = 'provium.cli.command_catalogs' module-attribute

The packaging entry-point group used to publish CLI plugins.

lineage_to_dot = graphviz.lineage_to_dot module-attribute

lineage_to_mermaid = mermaid.lineage_to_mermaid module-attribute

PROVIUM_CORE_API_VERSION = 1 module-attribute

__all__ = ['PROVIUM_CORE_API_VERSION', 'CLI_PLUGIN_API_VERSION', 'CLI_PLUGIN_ENTRY_POINT_GROUP', 'CLIPlugin', 'Artifact', 'ArtifactCatalog', 'ArtifactDefinition', 'ArtifactHeader', 'FinalizedArtifactInspection', 'ArtifactLineage', 'ArtifactReadBinding', 'ArtifactReader', 'ArtifactRecord', 'ArtifactReference', 'ArtifactWriter', 'BodyRegion', 'StagedArtifact', 'ArtifactWriteBinding', 'ConfigurationSnapshot', 'ImperativeProcedure', 'ImperativeProcedureExecution', 'CancellationToken', 'JsonValue', 'PreparedProcedure', 'Procedure', 'ProcedureCatalog', 'ProcedureCancelledError', 'ProcedureConfig', 'ProcedureConfigurationError', 'ProcedureContract', 'ProcedureContractMetadata', 'ProcedureDefinition', 'ProcedureExecutionRecord', 'ProcedureExecutionSession', 'ProcedureExecutionResult', 'ProcedureOutputResult', 'ProcedureExecutor', 'ProcedureIOField', 'ProcedureIOFieldMetadata', 'ProcedureInputField', 'ProcedureInputs', 'ProcedureOptionalInputField', 'ProcedureOptionalOutputField', 'ProcedureOutputField', 'ProcedureOutputs', 'ProcedureProcessContext', 'ProcedureRepeatedInputField', 'ProcedureRecord', 'ProcedureSetupContext', 'Session', '__version__', 'canonical_digest', 'canonical_json', 'canonical_json_bytes', 'compose_configuration', 'current_session', 'decode_header', 'discover_artifact_catalogs', 'discover_procedure_catalogs', 'encode_header', 'input', 'inspect_finalized_artifact', 'lineage_to_dot', 'lineage_to_mermaid', 'load_json_configuration', 'load_yaml_configuration', 'optional_input', 'optional_output', 'output', 'repeated_input', 'render_lineage', 'read_artifact_header', 'reset_artifact_discovery', 'reset_procedure_discovery', 'session', 'stage_artifact', 'validate_procedure_configuration'] module-attribute

JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]

Artifact

An artifact implementation with specialized reader and writer types.

open(path) classmethod

Open this artifact for reading within the active resource session.

create(path) classmethod

Open this artifact for writing within the active procedure callback.

bind_read(path) classmethod

Bind this artifact's reader type to a normalized path.

bind_write(path) classmethod

Bind this artifact's writer type to a normalized path.

ArtifactCatalog

Map persistent artifact identifiers to their definitions.

definitions property

Expose registered definitions through a read-only mapping.

register(definition)

Register and return an artifact definition.

resolve(identifier)

Return the definition registered for an identifier.

ArtifactDefinition dataclass

Describe an artifact implementation without importing it eagerly.

resolve()

Import and return the artifact class described by this definition.

ArtifactHeader dataclass

Metadata required to locate and identify one artifact body.

create(*, artifact_identifier, artifact_identity, body_length, body_digest, lineage, created_at=None, metadata_offset=PREFIX_SIZE) classmethod

Create a header with its body directly after encoded metadata.

ArtifactReadBinding dataclass

Bind a concrete artifact reader type to a local path or S3 URI.

open()

Open this artifact within the active resource session.

ArtifactReader

Own metadata and bounded body access for a concrete artifact reader.

inspect()

Return a value describing the body for human inspection.

ArtifactWriteBinding dataclass

Bind a concrete artifact writer type to a local path or S3 URI.

open()

Open the staged writer authorized for the active procedure callback.

ArtifactWriter

Own writable body access separately from container finalization.

BodyRegion

Expose one bounded artifact body using body-relative positions.

length property

Return the current logical body length.

closed property

Return whether this region has been closed.

check_context()

Require this region's live owner to be active.

check_access()

Require active ownership and an open region.

close()

Close this region and its stream when owned by the region.

tell()

Return the body-relative stream position.

seek(offset, whence=os.SEEK_SET)

Move to a body-relative position.

read(size=-1)

Read without crossing the finalized body boundary.

readinto(buffer)

Read body bytes into a writable buffer.

write(data)

Write body bytes and extend the logical body when necessary.

flush()

Flush the underlying stream.

StagedArtifact

Own one unpublished temporary container and its typed writer.

aborted property

Return whether this staged output has been abandoned.

published property

Return whether the staged container replaced its destination.

finalize_body()

Close the body and return its final length and SHA-256 digest.

publish(metadata)

Finalize and atomically replace the destination container.

abort()

Close and remove this unpublished output.

close()

Abandon the output when its owning session closes.

FinalizedArtifactInspection dataclass

Verified immutable metadata for one finalized artifact container.

CLIPlugin dataclass

A versioned command catalog published by an installed distribution.

CancellationToken

A thread-safe cooperative cancellation signal.

cancelled property

Return whether cancellation has been requested.

cancel()

Request cancellation; repeated requests have no additional effect.

raise_if_cancelled()

Raise when cancellation has been requested.

ConfigurationSnapshot dataclass

Canonical configuration values and their stable identities.

from_configuration(configuration) classmethod

Create a deterministic snapshot of a validated configuration.

ImperativeProcedure

Identify a procedure used through direct context-managed artifact access.

execute(*, inputs=(), outputs=None)

Create a single-use imperative execution context.

ImperativeProcedureExecution

Authorize explicit bindings and publish their provenance on success.

result property

Return the completed result, or None while execution is active.

PreparedProcedure

Own one configured procedure instance and its reusable setup state.

configuration property

Return the configuration shared by setup and every execution.

execute(*, inputs=None, outputs=None, cancellation=None)

Process one invocation on the prepared instance.

close()

Close the prepared instance exactly once.

Procedure

Bases: ABC

Base type for a concrete procedure implementation.

setup(context, configuration, inputs)

Prepare reusable state before processing begins.

process(context, configuration, inputs, outputs) abstractmethod

Process one invocation.

close()

Release state prepared by :meth:setup.

ProcedureCancelledError

Bases: RuntimeError

Raised when a procedure invocation observes cancellation.

ProcedureCatalog

Map persistent procedure identifiers to their definitions.

definitions property

Expose registered definitions through a read-only mapping.

register(definition)

Register and return a procedure definition.

resolve(identifier)

Return the definition registered for an identifier.

ProcedureConfig

Bases: BaseModel

Immutable, strictly validated configuration for a procedure.

ProcedureConfigurationError

Bases: ValueError

A Pydantic configuration failure annotated with procedure context.

errors()

Return Pydantic's structured validation details.

ProcedureContract

Lightweight configuration and I/O contract for a procedure.

ProcedureContractMetadata dataclass

Immutable, implementation-free metadata compiled from a contract.

configuration_schema property

Return an isolated, JSON-compatible configuration schema.

ProcedureDefinition dataclass

Describe a procedure implementation without importing it eagerly.

invocation_synopsis property

Return a direct-execution synopsis without resolving implementations.

resolve_contract()

Import, validate, and cache the procedure contract when needed.

resolve()

Import and return the procedure class described by this definition.

ProcedureExecutionResult dataclass

Describe one completed invocation and its named artifact outputs.

ProcedureExecutionSession

Own one invocation's child session, staged outputs, and lineage.

writers property

Return staged writers in declaration order.

outputs property

Return output references in declaration order.

lineage property

Return finalized execution lineage after successful publication.

result property

Return immutable metadata after successful publication.

stage_outputs(bindings)

Stage every output together using one provisional execution graph.

ProcedureExecutor

Resolve, validate, and prepare procedure implementations.

prepare(definition, *, configuration_layers=(), setup_inputs=None)

Create and set up one reusable procedure instance.

execute(definition, *, configuration_layers=(), setup_inputs=None, inputs=None, outputs=None, cancellation=None)

Prepare, process one invocation, and close the procedure.

ProcedureInputField

Bases: ProcedureIOField

A required input field whose instance value will be a read binding.

ProcedureInputs

Bases: _ProcedureIORecord

Base type for a procedure's declared input record.

ProcedureIOField

Shared immutable metadata for a declared procedure I/O field.

artifact property

Return the artifact definition required by this field.

direction property

Return whether this field reads an input or writes an output.

description property

Return the optional human-readable field description.

name property

Return the attribute name assigned by the declaring class.

minimum property

Return the required minimum number of bindings.

maximum property

Return the permitted maximum number of bindings.

required property

Return whether the field requires a binding.

repeated property

Return whether the field contains several ordered bindings.

is_declared_on(owner)

Return whether this descriptor was first assigned to owner.

ProcedureIOFieldMetadata dataclass

Immutable inspection metadata for one procedure I/O field.

required property

Return whether the field requires at least one binding.

ProcedureOptionalInputField

Bases: ProcedureIOField

An optional input field whose instance value may be absent.

ProcedureOptionalOutputField

Bases: ProcedureIOField

An optional output field whose instance value may be absent.

ProcedureOutputField

Bases: ProcedureIOField

A required output field whose instance value will be a write binding.

ProcedureOutputResult dataclass

Describe one declared output's produced or absent final state.

produced property

Return whether the optional output was produced and finalized.

ProcedureOutputs

Bases: _ProcedureIORecord

Base type for a procedure's declared output record.

ProcedureProcessContext

Bases: _ProcedureContext

Context supplied while a procedure processes one invocation.

ProcedureRepeatedInputField

Bases: ProcedureIOField

A repeated input field whose instance value is an ordered tuple.

repeated property

Return whether the field contains several ordered bindings.

ProcedureSetupContext

Bases: _ProcedureContext

Context supplied while a procedure prepares reusable state.

ArtifactLineage dataclass

Bases: _SerializableRecord

A normalized, mergeable graph of artifacts and producing executions.

for_execution(execution, output_records, input_lineages=()) classmethod

Extend merged input lineages with one completed execution.

merge(other)

Merge another compatible lineage into this graph.

artifact(reference)

Return the record matching an exact artifact reference.

producing_execution(reference)

Return the execution that produced an artifact.

ancestry(reference)

Return the subgraph needed to produce an artifact.

ArtifactRecord dataclass

Bases: _SerializableRecord

A finalized artifact digest and its producing execution.

ArtifactReference dataclass

Bases: _SerializableRecord

The persistent identity and catalog type of an artifact.

ProcedureExecutionRecord dataclass

Bases: _SerializableRecord

One procedure execution and its artifact edges.

ProcedureRecord dataclass

Bases: _SerializableRecord

A procedure identity and its optional configuration snapshot.

Session

Own resources within a single-use, nestable logical context.

readers property

Return every reader opened directly by this session.

inputs property

Return unique semantic artifact inputs in opening order.

input_lineage property

Return the merged lineage of every opened artifact.

manage(resource)

Register a resource to close when this session exits.

open_artifact(binding)

Open and verify one typed artifact binding.

decode_header(data)

Decode and validate a complete artifact header from bytes.

discover_artifact_catalogs()

Load and merge installed artifact catalogs.

encode_header(header)

Encode a fixed prefix and its canonical metadata.

read_artifact_header(path)

Read an artifact container's header without reading its body.

reset_artifact_discovery()

Clear cached artifact discovery state.

stage_artifact(binding, metadata, owner)

Create an adjacent temporary container for one typed output.

inspect_finalized_artifact(path, *, scratch_directory=None)

Fully verify a finalized artifact without resolving its artifact class.

canonical_digest(value)

Return the SHA-256 hex digest of canonical JSON bytes.

canonical_json(value)

Encode a JSON-domain value deterministically as text.

canonical_json_bytes(value)

Encode a JSON-domain value deterministically as UTF-8.

compose_configuration(layers)

Merge ordered raw configuration layers without mutating their values.

discover_procedure_catalogs()

Load and merge installed procedure catalogs.

input(artifact, *, description=None)

Declare one required procedure input.

load_json_configuration(path)

Load one raw configuration layer from a UTF-8 JSON object.

load_yaml_configuration(path)

Load one raw configuration layer from a UTF-8 YAML mapping.

optional_input(artifact, *, description=None)

Declare one optional procedure input.

optional_output(artifact, *, description=None)

Declare one optional procedure output.

output(artifact, *, description=None)

Declare one required procedure output.

repeated_input(artifact, *, minimum=0, maximum=None, description=None)

Declare an ordered collection of procedure inputs.

reset_procedure_discovery()

Clear cached procedure discovery state.

validate_procedure_configuration(procedure_identifier, configuration_type, values, *, source_layers=())

Validate raw values into the exact configuration subtype.

current_session()

Return the active session, if any.

render_lineage(lineage, *, format, backend='auto', show_artifact_identities=False, show_procedure_versions=False, show_execution_identities=False)

Render an artifact lineage with the selected optional backend.