Hyrax Verbs

The term “verb” describes the actions that Hyrax can perform. Each verb is available as a method on the Hyrax object in a notebook and (unless noted) as a subcommand of the hyrax CLI.

train

Train a model. The model and training data are specified via the configuration or by calling h.set_config() after creating a Hyrax instance.

Returns the trained torch.nn.Module in a notebook context.

Notebook

from hyrax import Hyrax

h = Hyrax()
model = h.train()

CLI

$ hyrax train

infer

Run inference using a trained model. If no model weights are specified, Hyrax automatically finds the most recently trained model in the results directory.

Returns a ResultDataset in a notebook context.

Notebook

h.infer()

CLI

$ hyrax infer

test

Evaluate a trained model on test data, computing metrics and logging results to MLflow and TensorBoard.

Returns a ResultDataset in a notebook context.

Notebook

h.test()

CLI

$ hyrax test

umap

Run UMAP on the output of inference to reduce high-dimensional embeddings to 2D (or 3D) for visualization. By default, Hyrax uses the most recent inference output. See the UMAP notebook for configuration options.

Returns a ResultDataset containing the reduced embeddings.

Notebook

h.umap()

CLI

$ hyrax umap [-i <path_to_inference_output>]

visualize

Interactively visualize the embedded space produced by the umap verb. Renders an interactive Holoviews/Bokeh scatter plot with linked data table and optional image thumbnails.

Note

Notebook-only. Not available from the CLI.

h.visualize(width=800, height=800)

prepare

Load and return the configured datasets without running any training or inference. Useful for inspecting data, verifying the pipeline, and prototyping prepare_inputs or collate functions.

Returns a dictionary of DataProvider objects keyed by split name (e.g. "train", "infer").

Note

Notebook-only. Not available from the CLI.

datasets = h.prepare()
sample = datasets["train"][0]

model

Resolve and return the model class (not an instantiated model) from the current configuration. Useful for inspecting or overriding prepare_inputs before training.

Note

Notebook-only. Not available from the CLI.

ModelClass = h.model()

lookup

Look up the inference result for a single object by its ID.

Returns a numpy.ndarray (the latent vector) or None if not found.

Defaults to using the most recent infer output directory as a data source.

Notebook

result = h.lookup(id="object_42")

CLI

$ hyrax lookup -i <object_id> [-r <results_dir>]

save_to_database

Insert inference results into a vector database for similarity search. Supports ChromaDB and Qdrant backends (configured via [vector_db]). By default uses the most recent inference output. See the vector database notebook for an end-to-end walkthrough.

Notebook

h.save_to_database()

CLI

$ hyrax save_to_database [-i <inference_dir> -o <database_dir>]

database_connection

Open a connection to an existing vector database for interactive similarity queries (search_by_id, search_by_vector, get_by_id).

Returns a vector database connection object.

Note

Notebook-only. Not available from the CLI.

db = h.database_connection()
neighbors = db.search_by_id("object_42", k=5)

to_onnx

Export a trained PyTorch model to ONNX format for portable, framework-free inference via the engine verb. By default uses the most recent results directory from the train verb.

Notebook

h.to_onnx()

CLI

$ hyrax to_onnx [--input-model-directory <dir>]

engine

Run inference using an exported ONNX model. Intended for production deployments that do not require PyTorch at runtime.

Notebook

h.engine()

CLI

$ hyrax engine [--model-directory <dir>]