Metadata-Version: 2.3
Name: syvain-metrics-api-client
Version: 0.0.332
Summary: Typed Python client for the Syvain Metrics REST API
Requires-Dist: niquests>=3.16.0
Requires-Dist: pydantic>=2.13.3
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.15.12 ; extra == 'dev'
Requires-Dist: ty>=0.0.34 ; extra == 'dev'
Requires-Python: >=3.10
Provides-Extra: dev
Description-Content-Type: text/markdown

# Syvain Metrics API Client

Use this typed Python client to find experiments and read stored metrics from
[Syvain Metrics](https://metrics.syvain.com/). To send metrics from a training
or evaluation job, use `syvain-metrics-collector` instead.

## Install

```bash
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:

```python
from syvain_metrics_api_client import SyvainMetricsApiClient

with SyvainMetricsApiClient("local", timeout=60.0) as client:
	experiments = client.list_experiments(
		status="done",
		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:

```python
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.
