vector-mtrl 0.2.0__py3-none-any.whl

mtrl/__init__.py

@@ -0,0 +1,144 @@
+"""Top-level package for mtrl."""
+
+from mtrl.domain import (
+    ArchiveId,
+    ArchiveLimits,
+    OperationRegistry,
+    Receipt,
+    RecordId,
+    RecordRef,
+    RevisionId,
+    SourcePolicy,
+    VerifyIssue,
+    VerifyPolicy,
+    VerifyResult,
+)
+from mtrl.exceptions import (
+    AnchorMismatchError,
+    ArchiveLimitError,
+    CheckpointExportWarning,
+    CommittedRecordMutationError,
+    DuplicateCheckpointError,
+    DuplicateRunError,
+    EnvironmentRecordError,
+    InsufficientCoverageError,
+    IntegrityMismatchError,
+    IntegrityRequiredError,
+    InvalidAggregationError,
+    InvalidFeatureError,
+    InvalidGridError,
+    InvalidMtrlFileError,
+    InvalidRecordRevisionError,
+    InvalidTransformationError,
+    ManifestVersionWarning,
+    MissingLoaderError,
+    MissingOptionalDependencyError,
+    MtrlError,
+    MtrlFormatError,
+    ReceiptUnavailableError,
+    RegistryAmbiguityError,
+    RegistryCollisionError,
+    ReplayIneligibleError,
+    ReplayPlanError,
+    SourceBundleError,
+    TableDuplicateError,
+    TableLimitError,
+    TablePlanError,
+    TableSelectionError,
+    UnexportableCheckpointError,
+    UnknownCheckpointError,
+    UnknownRunError,
+    UnrecognisedFileError,
+    UnsupportedCommittedValueError,
+    UnsupportedDatasetError,
+    UnsupportedExportFormatError,
+)
+from mtrl.features import register_supported_features, validate_feature
+from mtrl.integrity import (
+    ReceiptLimits,
+    forensic_inspect,
+    load_receipt,
+    receipt_to_text,
+    verify_archive,
+)
+from mtrl.models import (
+    AggregatedRun,
+    AggregationMethod,
+    InstrumentRun,
+    Manifest,
+    MaterialData,
+    MetadataField,
+    RunCheckpointPair,
+)
+from mtrl.mtrl import Mtrl
+from mtrl.processing import OperationDescriptor
+from mtrl.units import Unit
+
+__all__ = [
+    "CheckpointExportWarning",
+    "AggregatedRun",
+    "AggregationMethod",
+    "DuplicateCheckpointError",
+    "DuplicateRunError",
+    "InvalidAggregationError",
+    "InvalidGridError",
+    "InstrumentRun",
+    "InvalidMtrlFileError",
+    "InvalidTransformationError",
+    "Manifest",
+    "ManifestVersionWarning",
+    "MaterialData",
+    "MetadataField",
+    "Mtrl",
+    "Unit",
+    "MtrlError",
+    "MtrlFormatError",
+    "RunCheckpointPair",
+    "UnexportableCheckpointError",
+    "UnknownCheckpointError",
+    "UnknownRunError",
+    "UnrecognisedFileError",
+    "UnsupportedDatasetError",
+    "UnsupportedExportFormatError",
+    "ArchiveId",
+    "RecordId",
+    "RevisionId",
+    "RecordRef",
+    "SourcePolicy",
+    "ArchiveLimits",
+    "ReceiptLimits",
+    "OperationRegistry",
+    "OperationDescriptor",
+    "VerifyPolicy",
+    "VerifyResult",
+    "VerifyIssue",
+    "Receipt",
+    "verify_archive",
+    "forensic_inspect",
+    "load_receipt",
+    "receipt_to_text",
+    "UnsupportedCommittedValueError",
+    "CommittedRecordMutationError",
+    "InvalidRecordRevisionError",
+    "ArchiveLimitError",
+    "IntegrityMismatchError",
+    "AnchorMismatchError",
+    "InsufficientCoverageError",
+    "ReceiptUnavailableError",
+    "IntegrityRequiredError",
+    "RegistryCollisionError",
+    "RegistryAmbiguityError",
+    "MissingLoaderError",
+    "MissingOptionalDependencyError",
+    "ReplayIneligibleError",
+    "ReplayPlanError",
+    "TableSelectionError",
+    "TablePlanError",
+    "TableDuplicateError",
+    "TableLimitError",
+    "InvalidFeatureError",
+    "validate_feature",
+    "register_supported_features",
+    "EnvironmentRecordError",
+    "SourceBundleError",
+]

mtrl/_alignment_report.py

@@ -0,0 +1,105 @@
+"""Alignment report construction for committed aggregates."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mtrl._record_resolution import _resolve_exact_record
+from mtrl.exceptions import InvalidAggregationError, UnknownCheckpointError, UnknownRunError
+from mtrl.grids import (
+    AlignmentReport,
+    _axis_values,
+    _member_alignment,
+    _recorded_step_identifier,
+    _recorded_x_field,
+)
+from mtrl.models import CheckpointType
+
+if TYPE_CHECKING:
+    from mtrl.mtrl import Mtrl
+
+
+def _alignment_report_impl(
+    container: Mtrl,
+    run_id: str,
+    checkpoint_id: str,
+) -> AlignmentReport:
+    """Collect the recorded alignment facts of one committed aggregate.
+
+    The caller checks committed integrity before it calls this helper. The
+    helper reads committed records and stores nothing.
+
+    Args:
+        container: The container that holds the aggregate and its members.
+        run_id: The identifier of the run holding the aggregate checkpoint.
+        checkpoint_id: The identifier of the aggregated checkpoint.
+
+    Returns:
+        The immutable alignment report for that committed aggregate.
+
+    Raises:
+        UnknownRunError: If the container holds no run with that run_id.
+        UnknownCheckpointError: If the run holds no checkpoint with that
+            checkpoint_id.
+        InvalidAggregationError: If the checkpoint is not at stage
+            ``aggregated``, records no member references, a member reference
+            does not resolve to the exact committed record it names, the owning
+            run of a member record cannot be found, or a member or the
+            aggregate holds no readable axis.
+    """
+    run = container.get_run(run_id)
+    if run is None:
+        raise UnknownRunError(f"No run {run_id!r} in this Mtrl container")
+    checkpoint = run.get_checkpoint(checkpoint_id)
+    if checkpoint is None:
+        raise UnknownCheckpointError(f"No checkpoint {checkpoint_id!r} in run {run_id!r}")
+    if checkpoint.type is not CheckpointType.AGGREGATED:
+        raise InvalidAggregationError(
+            "alignment_report requires a checkpoint at stage 'aggregated'; "
+            f"checkpoint {checkpoint_id!r} of run {run_id!r} is at stage "
+            f"{checkpoint.type.value!r}."
+        )
+    member_refs = tuple(checkpoint.lineage.input_refs)
+    if not member_refs:
+        raise InvalidAggregationError(
+            "alignment_report requires an aggregation that records its "
+            f"member references; checkpoint {checkpoint_id!r} of run "
+            f"{run_id!r} records none."
+        )
+    x_field = _recorded_x_field(checkpoint)
+    aggregate_axis = _axis_values(
+        checkpoint, x_field, "alignment report aggregate", InvalidAggregationError
+    )
+    members = []
+    for member_ref in member_refs:
+        member_record = _resolve_exact_record(
+            container,
+            member_ref,
+            caller_name="alignment_report",
+            reference_label="member reference",
+            error_type=InvalidAggregationError,
+        )
+        member_run_id = container._record_run_map.get(member_record.record_id)
+        if member_run_id is None:
+            raise InvalidAggregationError(
+                "alignment_report cannot find the run that holds member "
+                f"record {member_record.record_id!r}."
+            )
+        members.append(
+            _member_alignment(
+                member_record,
+                run_id=member_run_id,
+                x_field=x_field,
+                resolve_record=container.get_record,
+            )
+        )
+    return AlignmentReport(
+        run_id=run_id,
+        checkpoint_id=checkpoint_id,
+        record_id=checkpoint.record_id,
+        method=_recorded_step_identifier(checkpoint),
+        x_field=x_field,
+        aggregate_points=int(aggregate_axis.size),
+        aggregate_span=float(aggregate_axis.max()) - float(aggregate_axis.min()),
+        members=tuple(members),
+    )

mtrl/_archive_documents.py

@@ -0,0 +1,73 @@
+"""Archive document normalisation and metadata decoding."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+from mtrl.exceptions import CanonicalisationError, InvalidArchiveStructureError
+from mtrl.integrity.canonical import decode_metadata_from_archive
+
+_CANONICAL_OPERATION_PARAMETER_PATHS = (
+    ("*", "lineage", "transformation", "parameters"),
+    ("*", "lineage", "provenance", "effective_parameters"),
+)
+
+
+def _normalise_new_object_list(
+    document: Any,
+    key: str,
+    label: str,
+) -> list[dict[str, Any]]:
+    """Read a list of objects from an array or named wrapper."""
+    if isinstance(document, Mapping):
+        if key in document:
+            document = document[key]
+        else:
+            identity_field = {
+                "checkpoints": "checkpoint_id",
+                "records": "record_id",
+                "revisions": "revision_id",
+                "runs": "run_id",
+            }.get(key)
+            if identity_field is not None and identity_field in document:
+                document = [document]
+            elif identity_field is not None:
+                document = [
+                    {
+                        **value,
+                        identity_field: value.get(identity_field, identity),
+                    }
+                    for identity, value in document.items()
+                    if isinstance(value, Mapping)
+                ]
+            else:
+                document = []
+    if not isinstance(document, list):
+        raise InvalidArchiveStructureError(f"New archive {label} document is not a list.")
+    if not all(isinstance(entry, Mapping) for entry in document):
+        raise InvalidArchiveStructureError(f"New archive {label} descriptors must be objects.")
+    return [cast(dict[str, Any], entry) for entry in document]
+
+
+def _deserialise_metadata_field(field_data: Any) -> Any:
+    """Decode one canonical metadata field with its typed value wrapper."""
+    if not isinstance(field_data, Mapping):
+        raise InvalidArchiveStructureError(
+            "Canonical metadata fields must be objects with a typed value wrapper."
+        )
+    serialised = dict(field_data)
+    if "value" not in serialised:
+        raise InvalidArchiveStructureError(
+            "Canonical metadata fields must contain a typed value wrapper."
+        )
+    try:
+        serialised["value"] = decode_metadata_from_archive(
+            serialised["value"],
+            archive_format="canonical",
+        )
+    except CanonicalisationError as error:
+        raise InvalidArchiveStructureError(
+            "Canonical metadata value is not a valid recursive typed wrapper."
+        ) from error
+    return serialised