ommx.artifact

Classes

`Artifact`	Reader for OMMX Artifacts.
`ArtifactArchive`	Helper class that provides a standard way to create an ABC using
`ArtifactArchiveBuilder`	Helper class that provides a standard way to create an ABC using
`ArtifactBase`	Helper class that provides a standard way to create an ABC using
`ArtifactBuilder`	Builder for OMMX Artifacts.
`ArtifactDir`	Helper class that provides a standard way to create an ABC using
`ArtifactDirBuilder`	Helper class that provides a standard way to create an ABC using

Functions

`get_image_dir`(→ pathlib.Path)	Get the directory path for a specific image in the local registry.
`get_images`(→ list[str])	Get all image names stored in the local registry.
`get_local_registry_root`(→ pathlib.Path)	Get the path to the local OMMX registry root directory.
`set_local_registry_root`(→ None)	Set the path to the local OMMX registry root directory.

Module Contents

class ommx.artifact.Artifact

Reader for OMMX Artifacts.

get_blob(digest: str | ommx._ommx_rust.Descriptor) → bytes

get_dataframe(descriptor: ommx._ommx_rust.Descriptor) → pandas.DataFrame: Get a pandas DataFrame from an artifact layer stored by ArtifactBuilder.add_dataframe()

get_instance(descriptor: ommx._ommx_rust.Descriptor) → ommx.v1.Instance: Get an instance from the artifact

get_json(descriptor: ommx._ommx_rust.Descriptor): Get a JSON object from an artifact layer stored by ArtifactBuilder.add_json()

get_layer(descriptor: ommx._ommx_rust.Descriptor) → ommx.v1.Instance | ommx.v1.Solution | numpy.ndarray

Get the layer object corresponding to the descriptor

This is dynamically dispatched based on the Descriptor.media_type.

get_layer_descriptor(digest: str) → ommx._ommx_rust.Descriptor

Look up a layer descriptor by digest

>>> artifact = Artifact.load("ghcr.io/jij-inc/ommx/random_lp_instance:4303c7f")
>>> layer = artifact.get_layer_descriptor("sha256:93fdc9fcb8e21b34e3517809a348938d9455e9b9e579548bbf018a514c082df2")
>>> print(layer.media_type)
application/org.ommx.v1.instance

get_ndarray(descriptor: ommx._ommx_rust.Descriptor) → numpy.ndarray: Get a numpy array from an artifact layer stored by ArtifactBuilder.add_ndarray()

get_parametric_instance(descriptor: ommx._ommx_rust.Descriptor) → ommx.v1.ParametricInstance: Get an parametric instance from the artifact

get_sample_set(descriptor: ommx._ommx_rust.Descriptor) → ommx.v1.SampleSet: Get a sample set from the artifact

get_solution(descriptor: ommx._ommx_rust.Descriptor) → ommx.v1.Solution

static load(image_name: str) → Artifact

Load an artifact stored as 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
>>> for layer in artifact.layers:
...    print(layer.digest)
sha256:93fdc9fcb8e21b34e3517809a348938d9455e9b9e579548bbf018a514c082df2

static load_archive(path: str | pathlib.Path) → Artifact

Load an artifact stored as a single file

>>> artifact = Artifact.load_archive("data/random_lp_instance.ommx")
>>> print(artifact.image_name)
ghcr.io/jij-inc/ommx/random_lp_instance:...
>>> for layer in artifact.layers:
...     print(layer.digest)
sha256:...

push(): Push the artifact to remote registry

property annotations: dict[str, str]

Annotations in the artifact manifest

>>> artifact = Artifact.load("ghcr.io/jij-inc/ommx/random_lp_instance:4303c7f")
>>> print(artifact.annotations['org.opencontainers.image.source'])
https://github.com/Jij-Inc/ommx
>>> print(artifact.annotations['org.opencontainers.image.description'])
Test artifact created by examples/artifact_archive.rs

property image_name: str | None

property instance: ommx.v1.Instance

Take the first instance layer in the artifact

If the artifact does not contain any instance layer, it raises an ValueError.
For multiple instance layers, use Artifact.get_instance() instead.

property layers: list[ommx._ommx_rust.Descriptor]

property parametric_instance: ommx.v1.ParametricInstance

Take the first parametric instance layer in the artifact

If the artifact does not have a parametric instance layer, it raises an ValueError.
For multiple parametric instance layers, use Artifact.get_parametric_instance() instead.

property sample_set: ommx.v1.SampleSet

Take the first sample set layer in the artifact

If the artifact does not have a sample set layer, it raises an ValueError.
For multiple sample set layers, use Artifact.get_sample_set() instead.

property solution: ommx.v1.Solution

Take the first solution layer in the artifact

If the artifact does not have a solution layer, it raises an ValueError.
For multiple solution layers, use Artifact.get_solution() instead.

class ommx.artifact.ArtifactArchive

Helper class that provides a standard way to create an ABC using inheritance.

static from_oci_archive(path: str) → ArtifactArchive

get_blob(digest: str) → bytes

push()

property annotations: dict[str, str]

property image_name: str | None

property layers: list[ommx._ommx_rust.Descriptor]

class ommx.artifact.ArtifactArchiveBuilder

Helper class that provides a standard way to create an ABC using inheritance.

add_annotation(key: str, value: str)

add_layer(media_type: str, blob: bytes, annotations: dict[str, str] = {}) → ommx._ommx_rust.Descriptor

build() → ArtifactArchive

static new(path: str, image_name: str) → ArtifactArchiveBuilder

static new_unnamed(path: str) → ArtifactArchiveBuilder

static temp() → ArtifactArchiveBuilder

class ommx.artifact.ArtifactBase

Helper class that provides a standard way to create an ABC using inheritance.

abstractmethod get_blob(digest: str) → bytes

abstractmethod push()

property annotations: dict[str, str]

Abstractmethod:

property image_name: str | None

Abstractmethod:

property layers: list[ommx._ommx_rust.Descriptor]

Abstractmethod:

class ommx.artifact.ArtifactBuilder

Builder for OMMX Artifacts.

add_annotation(key: str, value: str): Add annotation to the artifact itself.

add_dataframe(df: pandas.DataFrame, /, *, annotation_namespace: str = 'org.ommx.user.', **annotations: str) → ommx._ommx_rust.Descriptor

Add a pandas DataFrame to the artifact with parquet format

Example

>>> import pandas as pd
>>> df = pd.DataFrame({"a": [1, 2], "b": [3, 4]})

Store the DataFrame in the artifact with application/vnd.apache.parquet media type.

>>> builder = ArtifactBuilder.temp()
>>> _desc = builder.add_dataframe(df, title="test_dataframe")
>>> artifact = builder.build()

The title annotation is stored as org.ommx.user.title in the artifact, which can be accessed by Descriptor.annotations or Descriptor.user_annotations.

>>> layer = artifact.layers[0]
>>> print(layer.media_type)
application/vnd.apache.parquet
>>> print(layer.annotations)
{'org.ommx.user.title': 'test_dataframe'}
>>> print(layer.user_annotations)
{'title': 'test_dataframe'}

>>> df2 = artifact.get_dataframe(layer)
>>> assert df.equals(df2)

You can use another namespace for annotations via annotation_namespace argument.

>>> builder = ArtifactBuilder.temp()
>>> desc = builder.add_dataframe(df, annotation_namespace="org.ommx.user2.", title="test_dataframe")
>>> print(desc.annotations)
{'org.ommx.user2.title': 'test_dataframe'}

add_instance(instance: ommx.v1.Instance) → ommx._ommx_rust.Descriptor

Add an instance to the artifact with annotations

Example

>>> from ommx.v1 import Instance
>>> instance = Instance.empty()

Set annotations into the instance itself >>> instance.title = “test instance” >>> instance.add_user_annotation(“author”, “Alice”)

Add the instance to the artifact >>> builder = ArtifactBuilder.temp() >>> desc = builder.add_instance(instance) >>> print(desc.annotations[‘org.ommx.v1.instance.title’]) test instance >>> print(desc.annotations[‘org.ommx.user.author’]) Alice >>> artifact = builder.build()

Load the instance from the artifact by Artifact.get_instance() >>> instance2 = artifact.get_instance(desc) >>> print(instance2.title) test instance >>> print(instance2.get_user_annotations()) {‘author’: ‘Alice’}

add_json(obj, /, *, annotation_namespace: str = 'org.ommx.user.', **annotations: str) → ommx._ommx_rust.Descriptor

Add a JSON object to the artifact

Example

>>> obj = {"a": 1, "b": 2}

Store the object in the artifact with application/json media type.

>>> builder = ArtifactBuilder.temp()
>>> _desc = builder.add_json(obj, title="test_json")
>>> artifact = builder.build()

The title annotation is stored as org.ommx.user.title in the artifact, which can be accessed by Descriptor.annotations or Descriptor.user_annotations.

>>> layer = artifact.layers[0]
>>> print(layer.media_type)
application/json
>>> print(layer.annotations)
{'org.ommx.user.title': 'test_json'}
>>> print(layer.user_annotations)
{'title': 'test_json'}

add_layer(media_type: str, blob: bytes, annotations: dict[str, str] = {}) → ommx._ommx_rust.Descriptor: Low-level API to add any type of layer to the artifact with annotations. Use add_instance() or other high-level methods if possible.

add_ndarray(array: numpy.ndarray, /, *, annotation_namespace: str = 'org.ommx.user.', **annotations: str) → ommx._ommx_rust.Descriptor

Add a numpy ndarray to the artifact with npy format

Example

>>> import numpy as np
>>> array = np.array([1, 2, 3])

Store the array in the artifact with application/vnd.numpy media type. We can also add annotations to the layer.

>>> builder = ArtifactBuilder.temp()
>>> _desc = builder.add_ndarray(array, title="test_array")
>>> artifact = builder.build()

The title annotation is stored as org.ommx.user.title in the artifact, which can be accessed by Descriptor.annotations or Descriptor.user_annotations.

>>> layer = artifact.layers[0]
>>> print(layer.media_type)
application/vnd.numpy
>>> print(layer.annotations)
{'org.ommx.user.title': 'test_array'}
>>> print(layer.user_annotations)
{'title': 'test_array'}

Load the array from the artifact by Artifact.get_ndarray()

>>> ndarray = artifact.get_ndarray(layer)
>>> print(ndarray)
[1 2 3]

add_parametric_instance(instance: ommx.v1.ParametricInstance) → ommx._ommx_rust.Descriptor: Add a parametric instance to the artifact with annotations

add_sample_set(sample_set: ommx.v1.SampleSet) → ommx._ommx_rust.Descriptor: Add a sample set to the artifact with annotations

add_solution(solution: ommx.v1.Solution) → ommx._ommx_rust.Descriptor

Add a solution to the artifact with annotations

Example

>>> from ommx.v1 import Instance, Solution
>>> instance = Instance.empty()
>>> solution = instance.evaluate({})

Add the instance to the artifact first >>> builder = ArtifactBuilder.temp() >>> instance_desc = builder.add_instance(instance)

Set annotations into the solution itself >>> solution.instance = instance_desc.digest >>> solution.solver = “manual” >>> solution.add_user_annotation(“title”, “test solution”) >>> _desc = builder.add_solution(solution) >>> artifact = builder.build()

Load the solution from the artifact by Artifact.get_solution() >>> solution2 = artifact.get_solution(_desc) >>> print(solution2.instance) sha256:… >>> print(solution2.solver) manual >>> print(solution2.get_user_annotations()) {‘title’: ‘test solution’}

build() → Artifact: Build the artifact.

static for_github(org: str, repo: str, name: str, tag: str) → ArtifactBuilder

An alias for new() to create a new artifact in local registry with GitHub Container Registry image name

This also set the org.opencontainers.image.source annotation to the GitHub repository URL.

Example

Ready instance to be added to the artifact

>>> from ommx.testing import SingleFeasibleLPGenerator, DataType
>>> generator = SingleFeasibleLPGenerator(3, DataType.INT)
>>> instance = generator.get_v1_instance()

Build the artifact

>>> import uuid  # To generate a unique name for testing
>>> builder = ArtifactBuilder.for_github(
...    "Jij-Inc", "ommx", "single_feasible_lp", str(uuid.uuid4())
... )
>>> _desc = builder.add_instance(instance)
>>> artifact = builder.build()

>>> print(artifact.image_name)
ghcr.io/jij-inc/ommx/single_feasible_lp:...

static new(image_name: str) → ArtifactBuilder

Create a new artifact in local registry with a named image name

Example

Ready instance to be added to the artifact

>>> from ommx.testing import SingleFeasibleLPGenerator, DataType
>>> generator = SingleFeasibleLPGenerator(3, DataType.INT)
>>> instance = generator.get_v1_instance()

Image name for the artifact

>>> import uuid  # To generate a unique name for testing
>>> image_name = f"ghcr.io/jij-inc/ommx/single_feasible_lp:{uuid.uuid4()}"

Build the artifact

>>> builder = ArtifactBuilder.new(image_name)
>>> _desc = builder.add_instance(instance)
>>> artifact = builder.build()

>>> print(artifact.image_name)
ghcr.io/jij-inc/ommx/single_feasible_lp:...

static new_archive(path: str | pathlib.Path, image_name: str) → ArtifactBuilder

Create a new artifact archive with a named image name

Example

Ready instance to be added to the artifact

>>> from ommx.testing import SingleFeasibleLPGenerator, DataType
>>> generator = SingleFeasibleLPGenerator(3, DataType.INT)
>>> instance = generator.get_v1_instance()

File name and image name for the artifact.

>>> import uuid  # To generate a unique name for testing
>>> tag = uuid.uuid4()
>>> filename = f"data/single_feasible_lp.ommx.{tag}"
>>> image_name = f"ghcr.io/jij-inc/ommx/single_feasible_lp:{tag}"

Build the artifact

>>> builder = ArtifactBuilder.new_archive(filename, image_name)
>>> _desc = builder.add_instance(instance)
>>> artifact = builder.build()

>>> print(artifact.image_name)
ghcr.io/jij-inc/ommx/single_feasible_lp:...

static new_archive_unnamed(path: str | pathlib.Path) → ArtifactBuilder

Create a new artifact archive with an unnamed image name. This cannot be loaded into local registry nor pushed to remote registry.

Example

Ready instance to be added to the artifact

>>> from ommx.testing import SingleFeasibleLPGenerator, DataType
>>> generator = SingleFeasibleLPGenerator(3, DataType.INT)
>>> instance = generator.get_v1_instance()

File name for the artifact

>>> import uuid  # To generate a unique name for testing
>>> filename = f"data/single_feasible_lp.ommx.{uuid.uuid4()}"

Build the artifact

>>> builder = ArtifactBuilder.new_archive_unnamed(filename)
>>> _desc = builder.add_instance(instance)
>>> artifact = builder.build()

In this case, the Artifact.image_name is None.

>>> print(artifact.image_name)
None

static temp() → ArtifactBuilder

Create a new artifact as a temporary file. Note that this is insecure and should only be used for testing.

>>> builder = ArtifactBuilder.temp()
>>> artifact = builder.build()

Image name is set by random UUID, and can be pushed to https://ttl.sh/ registry. This will be removed after 1 hour.

>>> print(artifact.image_name)
ttl.sh/...-...-...-...-...:1h
>>> artifact.push()

class ommx.artifact.ArtifactDir

Helper class that provides a standard way to create an ABC using inheritance.

static from_image_name(image_name: str) → ArtifactDir

static from_oci_dir(path: str) → ArtifactDir

get_blob(digest: str) → bytes

push()

property annotations: dict[str, str]

property image_name: str | None

property layers: list[ommx._ommx_rust.Descriptor]

class ommx.artifact.ArtifactDirBuilder

Helper class that provides a standard way to create an ABC using inheritance.

add_annotation(key: str, value: str)

add_layer(media_type: str, blob: bytes, annotations: dict[str, str] = {}) → ommx._ommx_rust.Descriptor

build() → ArtifactDir

static for_github(org: str, repo: str, name: str, tag: str) → ArtifactDirBuilder

static new(image_name: str) → ArtifactDirBuilder

ommx.artifact.get_image_dir(image_name: str) → pathlib.Path

Get the directory path for a specific image in the local registry.

This function returns the filesystem path where the artifact with the given image name is stored in the local registry.

Parameters:: image_name – The OMMX image name in the format registry/repository:tag (e.g., ghcr.io/jij-inc/ommx/example:v1)
Returns:: Directory path for the image in the local registry
Return type:: Path

See also

get_local_registry_root(): Get the registry root directory Artifact: Load artifacts from the registry

ommx.artifact.get_images() → list[str]

Get all image names stored in the local registry.

This function scans the local registry and returns a list of all OMMX artifact image names that are currently stored locally.

Returns:: List of image names in the format registry/repository:tag
Return type:: list[str]

See also

get_local_registry_root(): Get the registry root directory get_image_dir(): Get the directory for a specific image Artifact: Load artifacts from the registry

ommx.artifact.get_local_registry_root() → pathlib.Path

Get the path to the local OMMX registry root directory.

The local registry is used to store OMMX artifacts locally. By default, it uses the XDG Base Directory specification, but can be overridden using set_local_registry_root() or the OMMX_LOCAL_REGISTRY_ROOT environment variable.

Returns:: Path to the local registry root directory
Return type:: Path

See also

set_local_registry_root(): Set a custom registry root path get_image_dir(): Get the directory for a specific image

ommx.artifact.set_local_registry_root(path: str | pathlib.Path) → None

Set the path to the local OMMX registry root directory.

This function allows you to override the default registry location. The change affects all subsequent artifact operations in the current process.

Parameters:: path – Path to the local registry root directory

See also

get_local_registry_root(): Get the current registry root path