Client API (matyan-client)

Public Python API of the matyan-client package. Install with pip install matyan-client (or from the repo) and import from matyan_client.

Main classes

`matyan_client.Run`

A single experiment run.

Tracks metrics, hyperparameters, custom objects (images, audio, etc.), and log records. Data is sent to the frontier via WebSocket (ingestion) and to the backend via REST (metadata). Call :meth:close when the run is finished so that the run is marked finalized and the write cache is cleared.

Parameters:

Name	Type	Description	Default
`run_hash`	`str \| None`	Existing run hash to resume, or None to create a new run.	`None`
`repo`	`str \| None`	Backend URL; also used as frontier URL if frontier_url is not set.	`None`
`frontier_url`	`str \| None`	Frontier WebSocket URL for ingestion (metrics, params, blobs).	`None`
`read_only`	`bool`	If True, no tracking or writes; used for query-only run handles.	`False`
`experiment`	`str \| None`	Experiment name to associate with the run.	`None`
`force_resume`	`bool`	If True, allow resuming a run that may already exist.	`False`
`system_tracking_interval`	`float \| None`	Seconds between system metric samples; None to disable.	`None`
`log_system_params`	`bool \| None`	If True, log system params (env, packages, git) at init.	`False`
`capture_terminal_logs`	`bool \| None`	If True, capture and send stdout/stderr to the UI. Usage:: `run = Run(experiment="baseline") run["hparams"] = {"lr": 0.01, "batch_size": 32} for step in range(100): run.track(loss, name="loss", step=step, context={"subset": "train"}) run.close()`	`True`

`active` `property`

True until :meth:close is called.

`archived` `property` `writable`

Whether the run is archived (hidden from default views).

`created_at` `property`

Creation time as a timezone-aware datetime (UTC).

`creation_time` `property`

Unix timestamp when the run was created.

`description` `property` `writable`

Optional run description.

`duration` `property`

Seconds between creation and finalization, or None if the run is still active.

`end_time` `property`

Unix timestamp when the run was finalized, or None if still active.

`experiment` `property` `writable`

Experiment name this run belongs to.

`finalized_at` `property`

Finalization time as a timezone-aware datetime (UTC), or None if still active.

`hash` `property`

Unique run identifier (hex string).

`name` `property` `writable`

Human-readable run name.

`props` `property`

Full run props (name, description, experiment, tags, etc.) from the backend.

`tags` `property`

Tag names attached to this run (fetched from the backend).

`del()`

On GC, close the run if it was not closed explicitly.

`delitem(key)`

Clear a run attribute from the local write cache (does not sync to backend).

`getitem(key)`

Get a run attribute by key; checks write cache then backend.

Parameters:

Name	Type	Description	Default
`key`	`str`	Attribute name or dotted path (e.g. `hparams`, `hparams.lr`).	required

Returns:

Type	Description
`Any`	The value for that key.

Raises:

Type	Description
`KeyError`	If the key is not found in cache or backend.

`repr()`

Return a short string representation of the run (hash and experiment).

`setitem(key, val)`

Set a run attribute (e.g. hyperparameters) by key.

Values are cached locally and sent to the frontier. Use dotted keys for nested structure (e.g. "hparams.lr").

Parameters:

Name	Type	Description	Default
`key`	`str`	Attribute name or dotted path (e.g. `hparams`, `hparams.lr`).	required
`val`	`AimObject`	Value to set (must be JSON-serializable or an Aim custom object).	required

`add_tag(value)`

Attach a tag to this run (sent via WebSocket or REST).

Parameters:

Name	Type	Description	Default
`value`	`str`	Tag name to add.	required

`close()`

Finalize the run, flush pending data, and release resources.

Marks the run as inactive, sends finish to the frontier, stops the resource tracker and blob uploader, and clears the write cache. Safe to call multiple times; subsequent calls are no-ops.

`collect_sequence_info(sequence_types=())`

Fetch trace overview for the given sequence types from the backend.

Parameters:

Name	Type	Description	Default
`sequence_types`	`str \| tuple[str, ...]`	Single type or tuple (e.g. `"metric"`, `("metric", "images")`); empty means all.	`()`

Returns:

Type	Description
`dict[str, list]`	Dict mapping bucket name to list of trace info dicts (e.g. `{"metric": [...]}`).

`get(key, default=None)`

Get a run attribute by key, or return default if not found.

`get_metric(name, context=None)`

Return trace info for a single metric by name and optional context.

Parameters:

Name	Type	Description	Default
`name`	`str`	Metric sequence name.	required
`context`	`Context \| None`	Optional context dict to match (e.g. subset).	`None`

Returns:

Type	Description
`dict \| None`	Trace info dict if found, else None.

`iter_metrics_info()`

Yield (metric name, context dict, self) for each metric trace.

Returns:

Type	Description
`Iterator[tuple[str, dict, Run]]`	Iterator of (name, context, run) tuples.

`log_artifact(path, name=None)`

Upload a single artifact file via presigned S3 URL (non-blocking).

Requires an active WebSocket connection to the frontier; blob notification is sent via WebSocket after upload. Open this run with read_only=False and a frontier URL to upload artifacts.

Parameters:

Name	Type	Description	Default
`path`	`str`	Local file path to upload.	required
`name`	`str \| None`	Optional artifact name/path in the run; defaults to the filename.	`None`

Raises:

Type	Description
`RuntimeError`	If the run has no WebSocket (e.g. read_only or no frontier).

`log_artifacts(path, name=None)`

Upload all files under a directory as artifacts (recursive).

Parameters:

Name	Type	Description	Default
`path`	`str`	Local directory path to upload.	required
`name`	`str \| None`	Optional prefix for artifact names; each file path is relative to the directory.	`None`

`log_debug(msg, **kwargs)`

Log a debug-level message and optional structured fields for this run.

`log_error(msg, **kwargs)`

Log an error-level message and optional structured fields for this run.

`log_info(msg, **kwargs)`

Log an info-level message and optional structured fields for this run.

`log_warning(msg, **kwargs)`

Log a warning-level message and optional structured fields for this run.

`metrics()`

Return an overview of all tracked metrics for this run.

Returns:

Type	Description
`list[dict]`	List of trace info dicts (name, context, etc.) for metric sequences.

`remove_tag(tag_name)`

Remove a tag from this run by name (sent via WebSocket or REST).

Parameters:

Name	Type	Description	Default
`tag_name`	`str`	Tag name to remove.	required

`set(key, val)`

Alias for self[key] = val; set a run attribute by key.

`track(value, name=None, step=None, epoch=None, *, context=None)`

Log a scalar or custom object for the given metric name and step.

Scalars are sent as metrics; objects with a json() method (e.g. :class:~matyan_client.objects.Image, :class:~matyan_client.objects.Audio) are serialized and uploaded (blobs go to S3 via presigned URL). If step is omitted, an auto-incrementing step per (name, context) is used.

Parameters:

Name	Type	Description	Default
`value`	`Any`	Metric value (float) or a custom object (Image, Text, etc.).	required
`name`	`str \| None`	Metric or sequence name (required).	`None`
`step`	`int \| None`	Step index; if None, auto-incremented per name/context.	`None`
`epoch`	`int \| None`	Optional epoch index for grouping steps.	`None`
`context`	`Context \| None`	Optional context dict to distinguish sequences (e.g. subset).	`None`

Raises:

Type	Description
`RuntimeError`	If the run is read-only or WebSocket is not initialized.
`ValueError`	If name is not provided.

`matyan_client.Repo`

Repository client that talks to the matyan-backend REST API.

Provides run listing, MatyanQL queries, run/experiment deletion, and aggregation helpers. The backend URL is taken from the argument or from MATYAN_BACKEND_URL if not provided.

Parameters:

Name	Type	Description	Default
`url`	`str \| None`	Backend base URL (e.g. `http://localhost:53800`); None to use settings. Usage:: `repo = Repo("http://localhost:53800") for run_info in repo.iter_runs(): print(run_info)`	`None`

`is_remote_repo` `property`

True; matyan Repo always uses a remote backend.

`repr()`

Return a short string representation of the repo (URL).

`available_sequence_types()` `staticmethod`

Return the list of sequence type names supported for queries.

`close()`

Close the underlying HTTP client and release resources.

`collect_params_info()`

Collect params (e.g. hyperparameters) for every run.

Returns:

Type	Description
`dict`	Dict mapping run hash to params dict (nested key-value structure).

`collect_sequence_info(sequence_types=('metric',))`

Collect trace/sequence info for the given types across all runs.

Parameters:

Name	Type	Description	Default
`sequence_types`	`tuple[str, ...]`	Tuple of sequence type names (e.g. `("metric", "images")`).	`('metric',)`

Returns:

Type	Description
`dict[str, dict[str, list]]`	Dict mapping run hash to dict of sequence type to list of trace info.

`default_repo()` `classmethod`

Return a Repo instance using the default backend URL from settings.

`delete_experiment(exp_id)`

Delete an experiment by ID (backend and async side effects).

Parameters:

Name	Type	Description	Default
`exp_id`	`str`	Experiment UUID or identifier.	required

Returns:

Type	Description
`bool`	True if the request succeeded, False on HTTP error.

`delete_run(run_hash)`

Delete a single run by hash (backend and async side effects).

Parameters:

Name	Type	Description	Default
`run_hash`	`str`	Run hash of the run to delete.	required

Returns:

Type	Description
`bool`	True if the request succeeded, False on HTTP error.

`delete_runs(run_hashes)`

Delete multiple runs by hash.

Parameters:

Name	Type	Description	Default
`run_hashes`	`list[str]`	List of run hashes to delete.	required

Returns:

Type	Description
`tuple[bool, list[str]]`	A tuple (all_succeeded, list of hashes that failed to delete).

`from_path(path)` `classmethod`

Return a Repo instance with the given URL (Aim compatibility: path is the backend URL).

Parameters:

Name	Type	Description	Default
`path`	`str`	Backend URL (e.g. `http://localhost:53800`).	required

`get_run(run_hash)`

Return a read-only Run proxy for the given run hash.

Parameters:

Name	Type	Description	Default
`run_hash`	`str`	Run hash (hex string) of the run.	required

Returns:

Type	Description
`Run \| None`	A read-only :class:`Run` instance, or None if the run does not exist or the request fails.

`is_remote_path(path)` `staticmethod`

Return True if the path looks like an HTTP(S) URL (Aim compatibility).

`iter_runs()`

Iterate over all runs as info dicts (hash, props, etc.).

Returns:

Type	Description
`Iterator[dict]`	Iterator of run info dicts from the backend.

`list_active_runs()`

Return run hashes for runs that are still active (not finalized).

Returns:

Type	Description
`list[str]`	List of run hash strings.

`list_all_runs()`

Return run hashes for all runs in the repository.

Returns:

Type	Description
`list[str]`	List of run hash strings.

`query_audios(query='')`

Query audio sequences with an optional MatyanQL filter.

`query_distributions(query='')`

Query distribution sequences with an optional MatyanQL filter.

`query_figure_objects(query='')`

Query figure sequences with an optional MatyanQL filter.

`query_images(query='')`

Query image sequences with an optional MatyanQL filter.

`query_metrics(query='')`

Run a MatyanQL metric query and return the result list.

`query_runs(query='', paginated=False, offset=None, limit=_DEFAULT_PAGE_LIMIT)`

Query runs with an optional MatyanQL expression.

Parameters:

Name	Type	Description	Default
`query`	`str`	MatyanQL query string; empty string means all runs.	`''`
`paginated`	`bool`	If True, return an iterator of pages (lists of run dicts); else a single list.	`False`
`offset`	`str \| None`	Optional run hash to start after (for pagination).	`None`
`limit`	`int`	Max runs per page when paginated.	`_DEFAULT_PAGE_LIMIT`

Returns:

Type	Description
`list[dict] \| Iterator[list[dict]]`	Either a list of run info dicts, or an iterator of such lists when paginated.

`query_texts(query='')`

Query text sequences with an optional MatyanQL filter.

`run_exists(run_hash)`

Return True if a run with the given hash exists in the backend.

`total_runs_count()`

Return the total number of runs in the repository.

Custom object types

Use these types with run.track() for images, audio, text, distributions, and figures.

`matyan_client.objects.Image`

A tracked image value for use with :meth:Run.track.

Accepts PIL Image, numpy array, file path (str or Path), or raw bytes. Numpy arrays require Pillow to be installed.

Parameters:

Name	Type	Description	Default
`image`	`ImageInput`	Image source: PIL Image, numpy array, path, or bytes.	required
`caption`	`str`	Optional caption for the UI.	`''`
`format_`	`str \| None`	Output format (e.g. `PNG`, `JPEG`); default `PNG`.	`None`
`quality`	`int`	JPEG quality 1-100 when format is JPEG.	`90`
`optimize`	`bool`	Whether to optimize when saving (e.g. PNG/JPEG). Usage:: `run.track(Image(pil_img, caption="epoch 5"), name="samples", step=5)`	`False`

`caption` `property`

Optional caption for the image in the UI.

`format` `property`

Image format (e.g. PNG, JPEG).

`height` `property`

Image height in pixels, if known (PIL/numpy only).

`size` `property`

Size of the encoded image in bytes.

`width` `property`

Image width in pixels, if known (PIL/numpy only).

`repr()`

Short string representation (format, size, caption).

`json()`

Return a dict suitable for serialization (type, base64 data, format, caption, dimensions).

`matyan_client.objects.Audio`

A tracked audio value for use with :meth:Run.track.

Accepts file path, raw bytes, I/O stream, or numpy array (converted to WAV). For numpy arrays, samples are normalized to 16-bit PCM if needed.

Parameters:

Name	Type	Description	Default
`data`	`AudioInput`	Audio source: path (str or Path), bytes, file-like, or 1D/2D numpy array.	required
`format_`	`str`	File format (e.g. `wav`, `mp3`); inferred from path if omitted.	`''`
`caption`	`str`	Optional caption for the UI.	`''`
`rate`	`int \| None`	Sample rate in Hz; used when encoding numpy arrays (default 22050). Usage:: `run.track(Audio("recording.wav", caption="sample"), name="audio", step=0)`	`None`

`caption` `property`

Optional caption for the audio in the UI.

`format` `property`

Audio format (e.g. wav, mp3).

`json()`

Return a dict suitable for serialization (type, base64 data, format, caption, rate).

`matyan_client.objects.Text`

A tracked text value for use with :meth:Run.track.

Parameters:

Name	Type	Description	Default
`text`	`str`	The string content to log. Usage:: `run.track(Text("prediction: cat"), name="predictions", step=0)`	required

`data` `property`

The text content.

`repr()`

Short string representation (first 60 chars of content).

`json()`

Return a dict suitable for serialization (type and data).

`matyan_client.objects.Distribution`

A tracked distribution (histogram) value for use with :meth:Run.track.

Can be created from raw samples (binned automatically) or from a pre-computed histogram with a bin range. Use :meth:from_histogram or :meth:from_samples for explicit factory methods.

Parameters:

Name	Type	Description	Default
`samples`	`Sequence[float \| int] \| None`	Raw sample values to bin into a histogram; omit if using hist/bin_range.	`None`
`bin_count`	`int`	Number of bins when building from samples (capped at 512).	`64`
`hist`	`Sequence[float \| int] \| None`	Pre-computed bin counts (use with bin_range).	`None`
`bin_range`	`tuple[float, float] \| None`	(low, high) range for the histogram (use with hist).	`None`

Raises:

Type	Description
`ValueError`	If neither (samples) nor (hist and bin_range) are provided. Usage:: `run.track(Distribution(samples), name="weights", step=0) run.track(Distribution.from_histogram(hist, bin_range), name="grads")`

`bin_count` `property`

Number of bins in the histogram.

`range` `property`

(low, high) range of the histogram.

`weights` `property`

Bin counts (or weights) for each bin.

`repr()`

Short string representation (bin count and range).

`from_histogram(hist, bin_range)` `classmethod`

Build a distribution from pre-computed bin counts and range.

Parameters:

Name	Type	Description	Default
`hist`	`Sequence[float \| int]`	Sequence of bin counts (or weights).	required
`bin_range`	`tuple[float, float]`	(low, high) range of the histogram.	required

`from_samples(samples, bin_count=64)` `classmethod`

Build a distribution by binning raw samples.

Parameters:

Name	Type	Description	Default
`samples`	`Sequence[float \| int]`	Raw sample values.	required
`bin_count`	`int`	Number of bins (capped at 512).	`64`

`json()`

Return a dict suitable for serialization (type, bin_count, range, data).

`matyan_client.objects.Figure`

A tracked figure value for use with :meth:Run.track.

Accepts a plotly Figure, a matplotlib Figure (converted via plotly.tools), or a dict (e.g. serialized figure JSON).

Parameters:

Name	Type	Description	Default
`obj`	`Any`	Plotly Figure, matplotlib Figure with savefig, or dict.	required

Raises:

Type	Description
`TypeError`	If the object type is not supported. Usage:: `import plotly.express as px fig = px.scatter(df, x="x", y="y") run.track(Figure(fig), name="scatter", step=0)`

`data` `property`

The serialized figure data (e.g. plotly JSON structure).

`repr()`

Short string representation (top-level keys of data).

`json()`

Return a dict suitable for serialization (type and data).

Client API (matyan-client)

Main classes

matyan_client.Run

active property

archived property writable

created_at property

creation_time property

description property writable

duration property

end_time property

experiment property writable

finalized_at property

hash property

name property writable

props property

tags property

__del__()

__delitem__(key)

__getitem__(key)

__repr__()

__setitem__(key, val)

add_tag(value)

close()

collect_sequence_info(sequence_types=())

get(key, default=None)

get_metric(name, context=None)

iter_metrics_info()

log_artifact(path, name=None)

log_artifacts(path, name=None)

log_debug(msg, **kwargs)

log_error(msg, **kwargs)

log_info(msg, **kwargs)

log_warning(msg, **kwargs)

metrics()

remove_tag(tag_name)

set(key, val)

track(value, name=None, step=None, epoch=None, *, context=None)

matyan_client.Repo

is_remote_repo property

__repr__()

available_sequence_types() staticmethod

close()

collect_params_info()

collect_sequence_info(sequence_types=('metric',))

default_repo() classmethod

delete_experiment(exp_id)

delete_run(run_hash)

delete_runs(run_hashes)

from_path(path) classmethod

get_run(run_hash)

is_remote_path(path) staticmethod

iter_runs()

list_active_runs()

list_all_runs()

query_audios(query='')

query_distributions(query='')

query_figure_objects(query='')

query_images(query='')

query_metrics(query='')

query_runs(query='', paginated=False, offset=None, limit=_DEFAULT_PAGE_LIMIT)

query_texts(query='')

run_exists(run_hash)

total_runs_count()

Custom object types

matyan_client.objects.Image

caption property

format property

height property

size property

width property

__repr__()

json()

matyan_client.objects.Audio

caption property

format property

json()

matyan_client.objects.Text

data property

__repr__()

json()

`matyan_client.Run`

`active` `property`

`archived` `property` `writable`

`created_at` `property`

`creation_time` `property`

`description` `property` `writable`

`duration` `property`

`end_time` `property`

`experiment` `property` `writable`

`finalized_at` `property`

`hash` `property`

`name` `property` `writable`

`props` `property`

`tags` `property`

`del()`

`delitem(key)`

`getitem(key)`

`repr()`

`setitem(key, val)`

`add_tag(value)`

`close()`

`collect_sequence_info(sequence_types=())`

`get(key, default=None)`

`get_metric(name, context=None)`

`iter_metrics_info()`

`log_artifact(path, name=None)`

`log_artifacts(path, name=None)`

`log_debug(msg, **kwargs)`

`log_error(msg, **kwargs)`

`log_info(msg, **kwargs)`

`log_warning(msg, **kwargs)`

`metrics()`

`remove_tag(tag_name)`

`set(key, val)`

`track(value, name=None, step=None, epoch=None, *, context=None)`

`matyan_client.Repo`

`is_remote_repo` `property`

`repr()`

`available_sequence_types()` `staticmethod`

`close()`

`collect_params_info()`

`collect_sequence_info(sequence_types=('metric',))`

`default_repo()` `classmethod`

`delete_experiment(exp_id)`

`delete_run(run_hash)`

`delete_runs(run_hashes)`

`from_path(path)` `classmethod`

`get_run(run_hash)`

`is_remote_path(path)` `staticmethod`

`iter_runs()`

`list_active_runs()`

`list_all_runs()`

`query_audios(query='')`

`query_distributions(query='')`

`query_figure_objects(query='')`

`query_images(query='')`

`query_metrics(query='')`

`query_runs(query='', paginated=False, offset=None, limit=_DEFAULT_PAGE_LIMIT)`

`query_texts(query='')`

`run_exists(run_hash)`

`total_runs_count()`

`matyan_client.objects.Image`

`caption` `property`

`format` `property`

`height` `property`

`size` `property`

`width` `property`

`repr()`

`json()`

`matyan_client.objects.Audio`

`caption` `property`

`format` `property`

`json()`

`matyan_client.objects.Text`

`data` `property`

`repr()`

`json()`

`matyan_client.objects.Distribution`

`bin_count` `property`

`range` `property`