Artifact envelopes and store

The artifact models are Pydantic envelopes for stable cache files:

  • ReplicateArtifact: output from one replicate;

  • ConditionArtifact: aggregate over replicates for one condition;

  • ComparisonArtifact: cross-condition statistical result;

  • ArtifactSidecarRef: validated reference to an artifact-owned sidecar.

ArtifactStore reads and writes canonical result.json, manifest files, and sidecars. Sidecar references are relative paths with recorded size and SHA-256 hashes.

Artifact envelope models for MDAnalysis extension-layer results.

polyzymd.analyses.mda.artifacts.is_raw_mdanalysis_results(value)[source]

Return whether a value is an MDAnalysis raw results container.

Detection is intentionally import-light and relies on module/class metadata so artifact validation never imports MDAnalysis.

Parameters:

value (Any) – Candidate value to inspect.

Returns:

True when value looks like an MDAnalysis Results object.

Return type:

bool

polyzymd.analyses.mda.artifacts.raw_mdanalysis_results_path(value)[source]

Return the nested path to raw MDAnalysis results, if present.

Parameters:

value (Any) – Candidate artifact field value.

Returns:

Human-readable nested path to the first raw results container, or None when no raw results are present.

Return type:

str or None

polyzymd.analyses.mda.artifacts.reject_raw_mdanalysis_results(value, *, field_name)[source]

Reject raw MDAnalysis Results objects in artifact fields.

Parameters:

  • value (Any) – Candidate artifact field value.

  • field_name (str) – Name used in validation diagnostics.

Returns:

The original value when no raw results are found.

Return type:

Any

Raises:

ValueError – Raised when raw MDAnalysis results are found recursively.

polyzymd.analyses.mda.artifacts.validate_artifact_relative_path(value)[source]

Validate an artifact-relative POSIX path string.

Parameters:

value (str) – Candidate path stored in a JSON artifact.

Returns:

Normalized relative path using POSIX separators.

Return type:

str

Raises:

ValueError – Raised when the path is empty, absolute, or contains parent traversal.

class polyzymd.analyses.mda.artifacts.ArtifactSidecarRef(*, path, sha256, size_bytes, media_type=None, metadata=<factory>, **extra_data)[source]

Bases: BaseModel

Relative reference to a sidecar file owned by an artifact store.

path: str
sha256: str
size_bytes: int
media_type: str | None
metadata: dict[str, Any]
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.artifacts.ArtifactManifest(*, schema_version='1', analysis_name, artifact_id=None, artifact_type='manifest', polyzymd_version=None, mdanalysis_version=None, inputs=<factory>, provenance=<factory>, sidecars=<factory>, metadata=<factory>, **extra_data)[source]

Bases: BaseModel

Manifest for one artifact directory and its sidecar files.

schema_version: str
analysis_name: str
artifact_id: str | None
artifact_type: str
polyzymd_version: str | None
mdanalysis_version: str | None
inputs: dict[str, Any]
provenance: dict[str, Any]
sidecars: list[ArtifactSidecarRef]
metadata: dict[str, Any]
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.artifacts.ArtifactEnvelope(*, schema_version='1', artifact_type='artifact', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, **extra_data)[source]

Bases: BaseModel

Extensible JSON envelope for MDAnalysis extension-layer artifacts.

schema_version: str
artifact_type: str
analysis_name: str
payload: dict[str, Any]
sidecars: list[ArtifactSidecarRef]
provenance: dict[str, Any]
metadata: dict[str, Any]
warnings: list[str]
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.artifacts.ReplicateArtifact(*, schema_version='1', artifact_type='replicate', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, condition_label, replicate, **extra_data)[source]

Bases: ArtifactEnvelope

Result artifact produced for one replicate trajectory.

artifact_type: Literal['replicate']
condition_label: str
replicate: int
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.artifacts.ConditionArtifact(*, schema_version='1', artifact_type='condition', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, condition_label, replicates=<factory>, source_replicates=<factory>, skipped_replicates=<factory>, **extra_data)[source]

Bases: ArtifactEnvelope

Aggregated artifact produced for one simulation condition.

artifact_type: Literal['condition']
condition_label: str
replicates: list[int]
source_replicates: list[dict[str, Any]]
skipped_replicates: list[dict[str, Any]]
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.artifacts.ComparisonArtifact(*, schema_version='1', artifact_type='comparison', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, conditions=<factory>, control_label=None, effective_control=None, **extra_data)[source]

Bases: ArtifactEnvelope

Cross-condition comparison artifact.

artifact_type: Literal['comparison']
conditions: list[str]
control_label: str | None
effective_control: str | None
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Filesystem artifact store for MDAnalysis extension-layer outputs.

exception polyzymd.analyses.mda.store.ArtifactStoreError[source]

Bases: MDAnalysisExtensionError

Error raised when artifact-store path or validation checks fail.

class polyzymd.analyses.mda.store.ArtifactStore(root)[source]

Bases: object

Store JSON artifacts and relative sidecars under one root directory.

__init__(root)[source]

Create an artifact store rooted at root.

Parameters:

root (str or Path) – Directory that owns artifact JSON files and sidecars.

write_replicate_result(artifact, path='result.json')[source]

Write a replicate artifact JSON file.

Parameters:

  • artifact (ReplicateArtifact) – Replicate artifact envelope to serialize.

  • path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Absolute path to the written JSON file.

Return type:

Path

read_replicate_result(path='result.json')[source]

Read a replicate artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Deserialized replicate artifact.

Return type:

ReplicateArtifact

write_condition_result(artifact, path='result.json')[source]

Write a condition artifact JSON file.

Parameters:

  • artifact (ConditionArtifact) – Condition artifact envelope to serialize.

  • path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Absolute path to the written JSON file.

Return type:

Path

read_condition_result(path='result.json')[source]

Read a condition artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Deserialized condition artifact.

Return type:

ConditionArtifact

write_comparison_result(artifact, path='result.json')[source]

Write a comparison artifact JSON file.

Parameters:

  • artifact (ComparisonArtifact) – Comparison artifact envelope to serialize.

  • path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Absolute path to the written JSON file.

Return type:

Path

read_comparison_result(path='result.json')[source]

Read a comparison artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Deserialized comparison artifact.

Return type:

ComparisonArtifact

write_manifest(manifest, path='manifest.json')[source]

Write an artifact manifest JSON file.

Parameters:

  • manifest (ArtifactManifest) – Manifest to serialize.

  • path (str or Path, optional) – Store-relative JSON path, by default "manifest.json".

Returns:

Absolute path to the written manifest.

Return type:

Path

read_manifest(path='manifest.json')[source]

Read an artifact manifest JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "manifest.json".

Returns:

Deserialized manifest.

Return type:

ArtifactManifest

register_sidecar(path, *, media_type=None, metadata=None)[source]

Register an existing store-relative sidecar file.

Parameters:

  • path (str or Path) – Store-relative sidecar path.

  • media_type (str or None, optional) – Optional sidecar content type.

  • metadata (dict[str, Any] or None, optional) – Sidecar metadata to copy into the reference.

Returns:

Relative sidecar reference with streamed SHA-256 and size metadata.

Return type:

ArtifactSidecarRef

write_npz_sidecar(path, *, compressed=True, media_type='application/x-npz', metadata=None, **arrays)[source]

Write NumPy arrays to an NPZ sidecar and register it.

Parameters:

  • path (str or Path) – Store-relative sidecar path.

  • compressed (bool, optional) – Whether to use numpy.savez_compressed, by default True.

  • media_type (str or None, optional) – Sidecar media type stored in the reference.

  • metadata (dict[str, Any] or None, optional) – Additional sidecar metadata.

  • **arrays (Any) – Named arrays forwarded to NumPy.

Returns:

Registered NPZ sidecar reference.

Return type:

ArtifactSidecarRef

resolve_sidecar(ref)[source]

Resolve a sidecar reference to an absolute path under the store root.

Parameters:

ref (ArtifactSidecarRef or str or Path) – Sidecar reference or store-relative path.

Returns:

Absolute sidecar path under the store root.

Return type:

Path

validate_sidecar(ref)[source]

Validate sidecar existence, size, path containment, and SHA-256.

Parameters:

ref (ArtifactSidecarRef) – Sidecar reference to validate.

Returns:

Absolute sidecar path when validation passes.

Return type:

Path

load_npz_sidecar(ref)[source]

Validate and open an NPZ sidecar.

Parameters:

ref (ArtifactSidecarRef) – Sidecar reference to validate before loading.

Returns:

Open numpy.load handle. Callers should use it as a context manager to close the underlying file promptly.

Return type:

Any

source_artifact_ref(path='result.json')[source]

Return a hashed reference for an artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative artifact path, by default "result.json".

Returns:

Relative path, SHA-256 digest, and size metadata for the artifact.

Return type:

dict[str, Any]