Artifact

Artifact#

class Artifact#

Reader for OMMX Artifacts.

An artifact is an OCI container image that stores OMMX data (instances, solutions, sample sets, etc.) as layers.

>>> artifact = Artifact.load("ghcr.io/jij-inc/ommx/random_lp_instance:4303c7f")
>>> print(artifact.image_name)
ghcr.io/jij-inc/ommx/random_lp_instance:4303c7f
get_blob(descriptor: Descriptor) → bytes#

Get raw bytes of a blob by Descriptor.

Registry and storage failures, including a missing CAS blob referenced by the Descriptor, raise RuntimeError.

get_dataframe(descriptor: Descriptor) → Any#

Get a pandas DataFrame from an artifact layer stored by add_dataframe().

A mismatched media type raises ValueError; registry and storage failures raise RuntimeError. pandas exceptions are preserved.

get_instance(descriptor: Optional[Descriptor] = None) → Instance#

Get an instance from the artifact.

  • If descriptor is None, returns the first instance layer.

  • If descriptor is given, returns the instance for that specific layer.

Raises ValueError if no instance layer is found, if the Descriptor has the wrong media type, or if the payload is malformed. Registry and storage failures raise RuntimeError.

get_json(descriptor: Descriptor) → Any#

Get a JSON object from an artifact layer stored by add_json().

A mismatched media type raises ValueError; registry and storage failures raise RuntimeError. JSON decoder exceptions are preserved.

get_layer(descriptor: Descriptor) → Any#

Get the layer object corresponding to the descriptor.

Dynamically dispatched based on media_type:

  • OMMX instance payloads return Instance

  • OMMX parametric instance payloads return ParametricInstance

  • OMMX solution payloads return Solution

  • OMMX sample-set payloads return SampleSet

  • application/vnd.numpy returns a numpy array

Raises ValueError for an unsupported media type. Registry and storage failures raise RuntimeError; exceptions raised by Python-backed decoders are preserved.

get_layer_descriptor(digest: str) → Descriptor#

Look up a layer descriptor by digest.

Raises ValueError when digest is malformed and KeyError when the digest is valid but is not present in the Artifact manifest.

get_ndarray(descriptor: Descriptor) → Any#

Get a numpy array from an artifact layer stored by add_ndarray().

A mismatched media type raises ValueError; registry and storage failures raise RuntimeError. NumPy exceptions are preserved.

get_parametric_instance(descriptor: Optional[Descriptor] = None) → ParametricInstance#

Get a parametric instance from the artifact.

  • If descriptor is None, returns the first parametric instance layer.

  • If descriptor is given, returns the parametric instance for that specific layer.

Raises ValueError if no parametric instance layer is found, if the Descriptor has the wrong media type, or if the payload is malformed. Registry and storage failures raise RuntimeError.

get_sample_set(descriptor: Optional[Descriptor] = None) → SampleSet#

Get a sample set from the artifact.

  • If descriptor is None, returns the first sample set layer.

  • If descriptor is given, returns the sample set for that specific layer.

Raises ValueError if no sample set layer is found, if the Descriptor has the wrong media type, or if the payload is malformed. Registry and storage failures raise RuntimeError.

get_solution(descriptor: Optional[Descriptor] = None) → Solution#

Get a solution from the artifact.

  • If descriptor is None, returns the first solution layer.

  • If descriptor is given, returns the solution for that specific layer.

Raises ValueError if no solution layer is found, if the Descriptor has the wrong media type, or if the payload is malformed. Registry and storage failures raise RuntimeError.

import_archive(path: str | PathLike | Path) → Artifact#

Import an artifact from a .ommx OCI archive file (or an OCI Image Layout directory) into the user’s v3 SQLite Local Registry, and return a handle to the imported registry entry.

Side effect (intentional): archive / directory contents are permanently written into the SQLite Local Registry under the default root ($XDG_DATA_HOME/ommx/ on Linux, $HOME/Library/Application Support/org.ommx.ommx/ on macOS, or $OMMX_LOCAL_REGISTRY_ROOT when set). Subsequent Artifact.load(image_name) calls resolve from SQLite without re-importing.

For a side-effect-free read that just surfaces the manifest / layer descriptors without writing into the registry, use Artifact.inspect_archive() instead.

If the input lacks an org.opencontainers.image.ref.name annotation, v3 synthesizes an anonymous Local Registry ref and imports the content under that name. This keeps v2 unnamed archives importable while still making the imported artifact addressable in SQLite.

>>> artifact = Artifact.import_archive("data/random_lp_instance.ommx")
>>> print(artifact.image_name)
ghcr.io/jij-inc/ommx/random_lp_instance:...
inspect_archive(path: str | PathLike | Path) → ArchiveManifest#

Read a .ommx OCI archive’s manifest and layer descriptors without importing it into the SQLite Local Registry. Useful when you want to inspect an archive’s contents (e.g. iterate layer media types or check the artifact type) without triggering a registry write — the analogue of ommx inspect <archive> from the CLI.

For full registry import (so the artifact is reachable by Artifact.load(image_name) later), use Artifact.import_archive().

>>> manifest = Artifact.inspect_archive("data/random_lp_instance.ommx")
>>> for layer in manifest.layers:
...     print(layer.media_type)
application/org.ommx.v1.instance
load(image_name: str) → Artifact#

Load an artifact stored as a container image in local or remote registry.

If the image is not found in local registry, it will try to pull from remote registry.

>>> artifact = Artifact.load("ghcr.io/jij-inc/ommx/random_lp_instance:4303c7f")
>>> print(artifact.image_name)
ghcr.io/jij-inc/ommx/random_lp_instance:4303c7f

Raises RemoteArtifactNotFoundError when the exact remote reference does not exist. Other remote access failures raise subclasses of RemoteArtifactError. An invalid image reference raises ValueError before any remote access is attempted.

load_archive(path: str | PathLike | Path) → Artifact#

Removed in v3 — use import_archive() or inspect_archive() instead.

In v2 Artifact.load_archive(file) opened a .ommx archive in place without touching the SQLite Local Registry. v3 changed that contract: archive ingest now writes the artifact permanently into the user’s persistent SQLite Local Registry. To make the semantic shift visible (rather than silently polluting the registry on upgrade), the v2 name raises an explicit migration error:

  • Artifact.import_archive(file) — the replacement with the v3 registry-write semantics.

  • Artifact.inspect_archive(file) — a side-effect-free read of the manifest / layer descriptors without registry import.

push() → None#

Push the artifact to remote registry.

save(path: str | PathLike | Path) → None#

Save the artifact as a .ommx OCI archive file at path.

The archive is an exchange-format export of the registry-resident artifact. Loading the archive back via Artifact.import_archive() reimports it into the SQLite Local Registry under the same image name; Artifact.inspect_archive() reads the manifest / layer descriptors without writing into the registry.

TRACE_OTLP_PROTOBUF_MEDIA_TYPE: str#

Media type of an Experiment Run trace encoded as OTLP protobuf.

property annotations: dict[str, str]#

Read-only property.

Annotations in the artifact manifest.

property image_name: Optional[str]#

Read-only property.

property instance: Instance#

Read-only property.

The first instance layer in the artifact.

Raises ValueError if no instance layer is found. For multiple instance layers, use get_instance() with a descriptor.

property layers: list[Descriptor]#

Read-only property.

property parametric_instance: ParametricInstance#

Read-only property.

The first parametric instance layer in the artifact.

Raises ValueError if no parametric instance layer is found. For multiple parametric instance layers, use get_parametric_instance() with a descriptor.

property sample_set: SampleSet#

Read-only property.

The first sample set layer in the artifact.

Raises ValueError if no sample set layer is found. For multiple sample set layers, use get_sample_set() with a descriptor.

property solution: Solution#

Read-only property.

The first solution layer in the artifact.

Raises ValueError if no solution layer is found. For multiple solution layers, use get_solution() with a descriptor.