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.

get_dataframe(descriptor: Descriptor) → Any#

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

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.

get_json(descriptor: Descriptor) → Any#

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

get_layer(descriptor: Descriptor) → Any#

Get the layer object corresponding to the descriptor.

Dynamically dispatched based on media_type:

  • application/org.ommx.v1.instance returns Instance

  • application/org.ommx.v1.solution returns Solution

  • application/vnd.numpy returns a numpy array

get_layer_descriptor(digest: str) → Descriptor#

Look up a layer descriptor by digest.

get_ndarray(descriptor: Descriptor) → Any#

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

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.

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.

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.

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
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.