Syvain Metrics API Client

Typed Python client for the Syvain Metrics REST API.

This package maps directly onto the REST surface for experiments, folders, metric query endpoints, annotations, and ingestion keys. If you only need to record metrics from a training or evaluation job, use syvain-metrics-collector instead.

Install

uv add syvain-metrics-api-client

Authentication

Use an explicit API key:

from syvain_metrics_api_client import SyvainMetricsApiClient

client = SyvainMetricsApiClient("ak_org_...")

Use installed Syvain CLI auth:

client = SyvainMetricsApiClient("local")

local reads ~/.config/syvain-metrics/auth.json.

Usage

from syvain_metrics_api_client import SyvainMetricsApiClient

client = SyvainMetricsApiClient("local")

experiment = client.create_experiment(
    "mamba-run-001",
    description="Baseline mamba training run",
    metadata={"model": "mamba"},
).experiment

client.ingest_metrics(
    experiment.id,
    [
        {
            "client_event_id": "mamba-run-001/loss/1",
            "name": "loss",
            "value": 0.42,
            "step": 1,
            "metadata": {"split": "train"},
        }
    ],
)

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

query_metric_series(...) uses the lossless series query API. It returns a list of column batches grouped by experiment, metric name, and complete metadata object. Each batch has parallel data.steps, data.timestamp, and data.value arrays. Metadata filter values and returned metadata values are plain strings; omit value to require only that the metadata key exists. Set metric_name on a selection to query one metric, or omit it to query every metric in the experiment.

Every metric must include a stable client_event_id. Reuse the same value when retrying the same event so ingestion can remain idempotent.

Metric names must be nonempty printable ASCII and at most 256 bytes. The client also requires the canonical s-prefixed, percent-encoded Series DB key segment to be at most 512 bytes. Characters such as /, spaces, +, and parentheses are supported and encoded internally; the original human-readable name is returned by queries.

Metric metadata is validated against the series backend contract before a request is sent: it must be a flat str -> str mapping with at most 32 keys, 128 UTF-8 bytes per key, 512 UTF-8 bytes per value, and 4096 UTF-8 bytes in its canonical JSON representation.

Ingest and annotation creation calls mint and cache ingestion keys per experiment. Call prepare_ingestion(...) to mint and cache the key before a timed write. General API calls use the configured API key directly.

Client Surface

Folders:

• list_folders(...)
• create_folder(...)
• get_folder(...)
• patch_folder(...)
• rename_folder(...)
• move_folder(...)

Experiments:

• list_experiments(...)
• create_experiment(...)
• get_experiment(...)
• update_experiment_status(...)
• move_experiment(...)

Metrics:

• query_metric_series(...)
• query_metrics_catalog(...)
• ingest_metrics(...)

Ingestion keys:

• prepare_ingestion(...)
• list_ingestion_keys(...)
• create_ingestion_key(...)
• revoke_ingestion_key(...)
• forget_ingestion_credential(...)

Annotations:

• list_annotations(...)
• create_annotation(...)

Authentication:

• auth_status()

Host and Timeouts

The client defaults to https://metrics.syvain.com.

client = SyvainMetricsApiClient(
    "ak_org_...",
    host="https://metrics.syvain.com",
    timeout=10.0,
    ingest_timeout=60.0,
)

timeout applies to ordinary API calls. ingest_timeout applies to metric and annotation ingestion calls.

Write Retries and Idempotency

The client retries transient request failures for write operations. Eligible POST and PATCH writes send a generated Idempotency-Key header and reuse that key across retry attempts for the same logical request. Metric ingestion, one-time ingestion-key creation, and POST-based queries do not send the header. The Metrics API currently ignores it, so a retry can repeat a non-metric write. The client keeps sending it so future server-side replay protection can take effect without requiring an SDK upgrade.

Metric ingestion does not send a request-level idempotency key. Its idempotency is controlled by each metric's client_event_id. Use deterministic IDs derived from the run, metric name, step, and series metadata when the same event may be retried by caller code.

Errors

All package-specific failures inherit from MetricsApiError.

• MetricsApiRequestError: the API returned an HTTP error or could not be reached
• MetricsApiResponseError: the API returned a successful response that did not match the expected schema
• MetricsApiAuthError: local CLI auth was requested but unavailable or invalid