Metadata-Version: 2.3
Name: syvain-metrics-api-client
Version: 0.0.345
Summary: Typed Python client for the Syvain Metrics REST API
Requires-Dist: jcs>=0.2.1
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.

`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

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