Syvain Metrics API Client

Use this typed Python client to find experiments and read stored metrics from Syvain Metrics. To send metrics from a training or evaluation job, use syvain-metrics-collector instead.

create_annotation() accepts text up to 16,000 characters and metadata up to 64 KiB, or 65,536 UTF-8 bytes, of compact JSON. Keys, nested values, and JSON punctuation count toward the metadata limit. Validation fails before any HTTP request. The SDK counts bytes using the API's JavaScript number formatting. The API also enforces the cap. Store larger data in an artifact and include its path or URL in the annotation. Existing larger annotations remain readable.

Install

uv add syvain-metrics-api-client

Read experiment metrics

Authenticate with the credentials saved by the Syvain Metrics CLI. Then find an experiment and query one metric:

from syvain_metrics_api_client import SyvainMetricsApiClient

with SyvainMetricsApiClient("local", timeout=60.0) as client:
	experiments = client.list_experiments(
		slug="mamba-run-001",
		limit=1,
	).experiments
	if not experiments:
		raise RuntimeError("No matching experiment found")

	experiment = experiments[0]
	catalog = client.query_metrics_catalog([experiment.id])
	batches = client.query_metric_series(
		[
			{
				"experiment_id": experiment.id,
				"metric_name": "loss",
				"metadata_filter": [
					{"key": "split", "value": "valid"},
				],
			}
		],
		order={"axis": "step", "direction": "asc"},
	)

for item in catalog:
	print(item.metric_name, item.metadata_keys)

for batch in batches:
	for step, timestamp, value in zip(
		batch.data.steps,
		batch.data.timestamp,
		batch.data.value,
		strict=True,
	):
		print(batch.metric_name, batch.metadata, step, timestamp, value)

Each MetricSeriesColumnBatch contains one experiment, metric name, and exact metadata mapping. Its steps, timestamp, and value arrays are parallel and have equal lengths.

query_metrics_catalog() returns the available metric names and metadata keys. It does not return values. Omit metric_name from a series selection to query every metric in an experiment. In a metadata filter, omit value to select every series that contains the key.

Set stream=True to parse an NDJSON response incrementally. The method still returns a complete list[MetricSeriesColumnBatch]. It requests application/vnd.syvain.metric-series+ndjson and verifies the final completion record against the received batch and row counts. A stream that ends before completion raises MetricsApiRequestError; partial results are not returned. Deploy the API support for this media type before upgrading streaming clients.

Authentication

SyvainMetricsApiClient("local") reads the credentials written by the Syvain Metrics CLI. Pass an API key directly when CLI credentials are unavailable:

client = SyvainMetricsApiClient("ak_org_...")

The client defaults to https://metrics.syvain.com. Pass host= only when you need another Metrics deployment.

Errors

Package errors inherit from MetricsApiError:

MetricsApiRequestError reports an HTTP failure or an unreachable API.
MetricsApiResponseError reports a successful response that violates the expected schema.
MetricsApiAuthError reports missing or invalid local CLI credentials.

Public methods and key response models carry API details in their docstrings. Use help(SyvainMetricsApiClient.query_metric_series) or your editor's Python documentation view to inspect a method.

Release files for syvain-metrics-api-client 0.0.345

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for syvain-metrics-api-client 0.0.345
File	Size	Uploaded
syvain_metrics_api_client-0.0.345.tar.gz	17.1 kB	Sep 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for syvain-metrics-api-client 0.0.345
File	Interpreter	ABI	Platform	Reset
syvain_metrics_api_client-0.0.345-py3-none-any.whl 19.8 kB Sep 11, 2026	Python 3	none	any	Details

Total release size: 37.0 kB

Release files / syvain_metrics_api_client-0.0.345.tar.gz

Download URL	syvain_metrics_api_client-0.0.345.tar.gz
Size	17.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`de10b581164a16418f18be06e13e98269eab4978f63baa1d6d61b7091ee8326a`
BLAKE2b-256 checksum How to use checksums	`0bc21623e0dd6c26be05ab3cebfabd0db3b4bd7b0d81256ec7553b7ba651c67b`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / syvain_metrics_api_client-0.0.345-py3-none-any.whl

Download URL	syvain_metrics_api_client-0.0.345-py3-none-any.whl
Size	19.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`234a951ad2be4570dd3ef53f3d04bb1d4badea2365cec69b98dd41482b1035f0`
BLAKE2b-256 checksum How to use checksums	`26ecc95dc6ec4424829209c72b06436f9bc531af7cd0232f8d6a81f62af229fc`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`