Metadata-Version: 2.4
Name: matyan-client
Version: 0.2.0
Summary: Matyan SDK — Aim-compatible client for experiment tracking
Author-email: Tigran Grigoryan <grigoryan.tigran119@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/4gt-104/matyan-core
Project-URL: Repository, https://github.com/4gt-104/matyan-core
Project-URL: Documentation, https://4gt-104.github.io/matyan-core/
Keywords: experiment-tracking,mlops,aim,sdk,metrics,machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: <4,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click~=8.0
Requires-Dist: httpx~=0.28.0
Requires-Dist: loguru~=0.7.0
Requires-Dist: matyan-api-models~=0.2.1
Requires-Dist: psutil~=7.0
Requires-Dist: pydantic~=2.0
Requires-Dist: pydantic-settings~=2.0
Requires-Dist: websockets~=15.0
Provides-Extra: image
Requires-Dist: Pillow>=9.0; extra == "image"
Requires-Dist: numpy>=1.21; extra == "image"
Provides-Extra: audio
Requires-Dist: numpy>=1.21; extra == "audio"
Provides-Extra: figure
Requires-Dist: plotly>=5.0; extra == "figure"
Provides-Extra: matplotlib
Requires-Dist: matplotlib>=3.5; extra == "matplotlib"
Requires-Dist: plotly>=5.0; extra == "matplotlib"
Provides-Extra: numpy
Requires-Dist: numpy>=1.21; extra == "numpy"
Provides-Extra: gpu
Requires-Dist: nvidia-ml-py>=11.0; extra == "gpu"
Provides-Extra: keras
Requires-Dist: keras>=2.0; extra == "keras"
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.0; extra == "tensorflow"
Provides-Extra: pytorch
Requires-Dist: torch>=1.9; extra == "pytorch"
Provides-Extra: pytorch-lightning
Requires-Dist: lightning>=2.0; python_version >= "3.10" and extra == "pytorch-lightning"
Requires-Dist: torchvision>=0.15.0; extra == "pytorch-lightning"
Requires-Dist: omegaconf>=2.0; extra == "pytorch-lightning"
Provides-Extra: pytorch-ignite
Requires-Dist: pytorch-ignite>=0.4; extra == "pytorch-ignite"
Requires-Dist: omegaconf>=2.0; extra == "pytorch-ignite"
Provides-Extra: hugging-face
Requires-Dist: transformers>=4.0; extra == "hugging-face"
Provides-Extra: distributed-hugging-face
Requires-Dist: transformers>=4.0; extra == "distributed-hugging-face"
Requires-Dist: accelerate>=0.20; extra == "distributed-hugging-face"
Provides-Extra: xgboost
Requires-Dist: xgboost>=1.0; extra == "xgboost"
Provides-Extra: lightgbm
Requires-Dist: lightgbm>=3.0; extra == "lightgbm"
Provides-Extra: catboost
Requires-Dist: catboost>=1.0; extra == "catboost"
Provides-Extra: optuna
Requires-Dist: optuna>=3.0; extra == "optuna"
Provides-Extra: keras-tuner
Requires-Dist: keras-tuner>=1.0; extra == "keras-tuner"
Provides-Extra: prophet
Requires-Dist: prophet>=1.0; extra == "prophet"
Provides-Extra: sb3
Requires-Dist: stable-baselines3>=1.0; extra == "sb3"
Provides-Extra: acme
Requires-Dist: dm-acme>=0.4; extra == "acme"
Provides-Extra: fastai
Requires-Dist: fastai>=2.0; extra == "fastai"
Requires-Dist: ipython; extra == "fastai"
Provides-Extra: paddle
Requires-Dist: paddlepaddle>=2.0; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "paddle"
Provides-Extra: mxnet
Requires-Dist: mxnet>=1.9; extra == "mxnet"
Provides-Extra: adapters-all
Requires-Dist: matyan-client[keras]; extra == "adapters-all"
Requires-Dist: matyan-client[tensorflow]; extra == "adapters-all"
Requires-Dist: matyan-client[pytorch]; extra == "adapters-all"
Requires-Dist: matyan-client[pytorch-lightning]; extra == "adapters-all"
Requires-Dist: matyan-client[pytorch-ignite]; extra == "adapters-all"
Requires-Dist: matyan-client[hugging-face]; extra == "adapters-all"
Requires-Dist: matyan-client[distributed-hugging-face]; extra == "adapters-all"
Requires-Dist: matyan-client[xgboost]; extra == "adapters-all"
Requires-Dist: matyan-client[lightgbm]; extra == "adapters-all"
Requires-Dist: matyan-client[catboost]; extra == "adapters-all"
Requires-Dist: matyan-client[optuna]; extra == "adapters-all"
Requires-Dist: matyan-client[keras-tuner]; extra == "adapters-all"
Requires-Dist: matyan-client[prophet]; extra == "adapters-all"
Requires-Dist: matyan-client[sb3]; extra == "adapters-all"
Requires-Dist: matyan-client[acme]; extra == "adapters-all"
Requires-Dist: matyan-client[fastai]; extra == "adapters-all"
Requires-Dist: matyan-client[paddle]; extra == "adapters-all"
Requires-Dist: matyan-client[mxnet]; extra == "adapters-all"
Provides-Extra: convert
Requires-Dist: tensorflow-cpu>=2.15; platform_machine != "aarch64" and extra == "convert"
Requires-Dist: tensorflow>=2.15; platform_machine == "aarch64" and extra == "convert"
Requires-Dist: pillow>=9.0; extra == "convert"
Requires-Dist: tbparse~=0.0.8; extra == "convert"
Requires-Dist: tqdm~=4.0; extra == "convert"
Requires-Dist: numpy>=1.21; extra == "convert"
Requires-Dist: pandas>=1.5; extra == "convert"
Requires-Dist: click~=8.0; extra == "convert"
Provides-Extra: extended
Requires-Dist: matyan-client[image]; extra == "extended"
Requires-Dist: matyan-client[audio]; extra == "extended"
Requires-Dist: matyan-client[figure]; extra == "extended"
Requires-Dist: matyan-client[matplotlib]; extra == "extended"
Requires-Dist: matyan-client[numpy]; extra == "extended"
Requires-Dist: matyan-client[gpu]; extra == "extended"
Dynamic: license-file

# Matyan Client

**Aim-compatible Python SDK for experiment tracking.** The matyan-client sends run data to the Matyan **frontier** (WebSocket) and **backend** (REST): metrics, hyperparameters, custom objects (images, audio, figures), and log records. Use the same Run + Repo API you know from Aim, with optional framework adapters for Keras, PyTorch Lightning, Hugging Face, and others.

- **Run** — Create and manage a single experiment run; track scalars and custom objects, set hparams, add tags, log messages, upload artifacts.
- **Repo** — Query runs with MatyanQL, list/delete runs and experiments, aggregate sequence and params info.
- **Custom objects** — `Image`, `Audio`, `Figure`, `Text`, `Distribution` for use with `run.track()` (optional extras for PIL/numpy/plotly).
- **Adapters** — Callbacks and loggers for Keras, TensorFlow, PyTorch Lightning, Hugging Face, XGBoost, LightGBM, CatBoost, Optuna, and more (install only the extras you need).
- **Python 3.10+** — Fully typed; compatible with existing Aim-style scripts (change imports and use `Repo(url=...)` instead of a local path).

---

## Installation

**Base install** (no optional dependencies):

```bash
python3 -m pip install matyan-client
# or with uv
uv add matyan-client
```

Core features work out of the box: `Run`, `Repo`, scalar metrics via `track()`, hyperparameters, tags, structured log methods, artifact uploads (presigned S3), and the backup/restore/convert CLI.

### Optional dependencies

Install extras with brackets, e.g. `python3 -m pip install matyan-client[image,figure]` or `uv add "matyan-client[image,figure]"`.

#### Custom objects and media

| Extra        | Adds              | Use case                                      |
|--------------|-------------------|-----------------------------------------------|
| `image`      | Pillow, numpy     | `Image` from PIL Image, numpy array, path, or bytes |
| `audio`      | numpy             | `Audio` from path, bytes, or numpy array (WAV)    |
| `figure`     | plotly            | `Figure` from plotly Figure                       |
| `matplotlib` | matplotlib, plotly | `Figure` from matplotlib (via plotly.tools)   |
| `numpy`      | numpy             | Faster Distribution histograms; used by Image/Audio and some adapters |

#### System and serialization

| Extra    | Adds           | Use case                                                       |
|----------|----------------|----------------------------------------------------------------|
| `gpu`    | nvidia-ml-py   | GPU stats in background tracker when `system_tracking_interval` is set |

#### Framework adapters

Install only the frameworks you use:

| Extra                     | Adapter use                          |
|---------------------------|--------------------------------------|
| `keras`                   | Keras `MatyanCallback`               |
| `tensorflow`              | TensorFlow/Keras callback            |
| `pytorch`                 | PyTorch helpers (e.g. `track_params_dists`, `track_gradients_dists`) |
| `pytorch-lightning`       | Lightning `MatyanLogger`             |
| `pytorch-ignite`          | Ignite logger and handlers           |
| `hugging-face`            | Transformers `MatyanCallback`        |
| `distributed-hugging-face`| Distributed Transformers training    |
| `xgboost`, `lightgbm`, `catboost` | Boosting callbacks/loggers   |
| `optuna`                  | Optuna callback                      |
| `keras-tuner`             | Keras Tuner callback                 |
| `prophet`                 | Prophet logger                       |
| `sb3`                     | Stable-Baselines3 callback           |
| `acme`                    | Acme logger/writer                   |
| `fastai`                  | FastAI callback                      |
| `paddle`                  | PaddlePaddle callback (no wheel on linux aarch64) |
| `mxnet`                   | MXNet handler                        |

#### Bundles

| Extra           | Contents                                                                 |
|-----------------|--------------------------------------------------------------------------|
| `extended`      | `image`, `audio`, `figure`, `matplotlib`, `numpy`, `gpu`                 |
| `adapters-all`  | All adapter extras listed above                                         |

#### Conversion

| Extra    | Use case                                      |
|----------|-----------------------------------------------|
| `convert`| TensorBoard event logs → Matyan backup (tensorflow, tbparse, pillow, etc.) |

**Install examples:**

```bash
# Images and figures (Pillow, numpy, plotly)
python3 -m pip install matyan-client[image,figure]

# GPU system metrics
python3 -m pip install matyan-client[gpu]

# Keras and PyTorch Lightning adapters
python3 -m pip install matyan-client[keras,pytorch-lightning]

# Full media + GPU, no adapters
python3 -m pip install matyan-client[extended]

# All framework adapters
python3 -m pip install matyan-client[adapters-all]

# TensorBoard conversion
python3 -m pip install matyan-client[convert]
```

---

## Configuration

Settings use **environment variables** with the `MATYAN_` prefix (see `matyan_client.config.Settings`):

| Variable                      | Default                     | Description                    |
|------------------------------|-----------------------------|--------------------------------|
| `MATYAN_FRONTIER_URL`        | `http://localhost:53801`    | Frontier WebSocket (ingestion) |
| `MATYAN_BACKEND_URL`         | `http://localhost:53800`   | Backend REST API               |
| `MATYAN_S3_ENDPOINT`         | `http://localhost:9000`     | S3/MinIO for artifact uploads  |
| `MATYAN_WS_VERBOSE`          | `false`                     | Verbose WebSocket logging      |
| `MATYAN_WS_QUEUE_MAX_MEMORY_MB` | `512`                    | Max in-memory queue size (MB)  |
| `MATYAN_WS_HEARTBEAT_INTERVAL`  | `10`                    | Heartbeat interval (seconds)   |
| `MATYAN_WS_BATCH_INTERVAL_MS`   | `50`                    | Batch send interval (ms)       |
| `MATYAN_WS_BATCH_SIZE`       | `100`                      | Max messages per batch         |
| `MATYAN_WS_RETRY_COUNT`      | `2`                        | Send retries on failure        |

You can override URLs per instance: `Run(repo=..., frontier_url=...)`, `Repo(url=...)`.

---

## Quick start

```python
from matyan_client import Run

run = Run(experiment="my-experiment")
run["hparams"] = {"lr": 0.01, "batch_size": 32}

for step in range(100):
    loss = 0.1 / (step + 1)  # placeholder
    run.track(loss, name="loss", step=step, context={"subset": "train"})

run.close()
```

With env set (e.g. `MATYAN_BACKEND_URL`, `MATYAN_FRONTIER_URL`), the run is created on the server and metrics are sent to the frontier. View runs in the Matyan UI.

---

## Run

**Create:** `Run()`, `Run(experiment="name")`, or `Run(run_hash=..., repo=...)` to resume an existing run.

**Attributes and params:**

- `run["hparams"] = {...}` or dotted keys (e.g. `run["hparams.lr"] = 0.01`)
- `run.name`, `run.experiment`, `run.description`, `run.archived` (get/set)
- `run.add_tag("tag-name")`, `run.remove_tag("tag-name")`

**Tracking:**

- `run.track(value, name="loss", step=0, context={"subset": "train"}, epoch=0)` — log a scalar or a custom object (Image, Audio, etc.). If `step` is omitted, an auto-incrementing step per `(name, context)` is used.
- Custom objects (Image, Audio, Figure, Text, Distribution) are serialized and large blobs (image/audio) are uploaded to S3 via presigned URLs.

**Logging:**

- `run.log_info(msg, **kwargs)`, `run.log_warning`, `run.log_error`, `run.log_debug` — structured log records sent to the UI.

**Artifacts:**

- `run.log_artifact(path, name=...)` — upload a single file
- `run.log_artifacts(dir_path, name=...)` — upload all files under a directory recursively

**Lifecycle:**

- `run.close()` finalizes the run and flushes pending data. You can rely on `__del__` to close if the run is garbage-collected. For read-only access (e.g. from `Repo.get_run()`), use `Run(run_hash=..., read_only=True)`.

**System tracking (optional):**

- Constructor args: `system_tracking_interval` (float seconds; `None` to disable), `log_system_params`, `capture_terminal_logs`. GPU metrics require the `gpu` extra (nvidia-ml-py).

---

## Repo

**Create:** `Repo()`, `Repo(url=...)`, or `Repo.from_path(url)`. The repo talks to the Matyan backend REST API.

**Runs:**

- `repo.get_run(run_hash)` — returns a read-only `Run` or `None`
- `repo.iter_runs()`, `repo.list_all_runs()`, `repo.list_active_runs()`, `repo.total_runs_count()`

**Query (MatyanQL):**

- `repo.query_runs(query="", paginated=False, offset=..., limit=...)`
- `repo.query_metrics(query)`, `repo.query_images(query)`, `repo.query_audios(query)`, `repo.query_figure_objects(query)`, `repo.query_distributions(query)`, `repo.query_texts(query)`

**Management:**

- `repo.delete_run(run_hash)`, `repo.delete_runs([...])`, `repo.delete_experiment(exp_id)`

**Aggregation:**

- `repo.collect_sequence_info(sequence_types=...)`, `repo.collect_params_info()`

Call `repo.close()` when finished to release the HTTP client.

---

## Custom objects

Import from `matyan_client`: `Image`, `Audio`, `Figure`, `Text`, `Distribution`. Use with `run.track(obj, name="...", step=...)`.

| Type          | Inputs / factories                    | Extras              |
|---------------|---------------------------------------|---------------------|
| **Image**     | PIL Image, numpy array, path, or bytes; optional `caption`, `format_`, `quality`, `optimize` | `image` (Pillow + numpy) for non-file sources |
| **Audio**     | Path, bytes, file-like, or numpy (WAV); optional `format_`, `caption`, `rate` | `audio` (numpy) for numpy arrays |
| **Figure**    | plotly Figure, matplotlib Figure (via plotly.tools), or dict | `figure` (plotly); `matplotlib` for matplotlib conversion |
| **Text**      | Plain string                          | None                |
| **Distribution** | Samples or pre-computed histogram; `Distribution.from_histogram(hist, bin_range)`, `Distribution.from_samples(samples, bin_count)` | Optional `numpy` for faster histogramming |

Example:

```python
from matyan_client import Run, Image, Distribution

run = Run(experiment="demo")
run.track(Image("sample.png", caption="epoch 0"), name="samples", step=0)
run.track(Distribution.from_samples([0.1, 0.2, 0.3], bin_count=10), name="weights", step=0)
run.close()
```

---

## Framework adapters

Adapters plug into training loops and log metrics/hparams to Matyan. Import from `matyan_client.adapters.<module>`. If the framework is not installed, you get a clear error with an install hint (install the matching extra).

**Examples:**

**Keras:**

```python
from matyan_client.adapters.keras import MatyanCallback

model.fit(x, y, callbacks=[MatyanCallback(experiment="my-exp", repo="http://localhost:53800")])
```

**PyTorch Lightning:**

```python
from matyan_client.adapters.pytorch_lightning import MatyanLogger

trainer = Trainer(logger=MatyanLogger(experiment="my-exp"))
```

**Hugging Face Transformers:**

```python
from matyan_client.adapters.hugging_face import MatyanCallback

trainer = Trainer(..., callbacks=[MatyanCallback(experiment="my-exp")])
```

Pass `repo=` (backend URL) when constructing the adapter if you are not using `MATYAN_BACKEND_URL`. See the adapter docstrings and the [integrations guide](https://4gt-104.github.io/matyan-core/) for more frameworks (XGBoost, LightGBM, CatBoost, Optuna, FastAI, SB3, etc.).

---

## CLI

The `matyan-client` command is available after installation.

**Status** — Show backend, optional frontier, and client versions:

```bash
matyan-client status [--backend-url URL] [--frontier-url URL]
```

**Backup** — Create a backup via the backend REST API (no direct FDB access):

```bash
matyan-client backup OUTPUT_PATH [--backend-url URL] [--runs RUN1,RUN2] [--experiment NAME] [--since ISO_DATETIME] [--no-blobs] [--compress]
```

**Restore** — Restore a backup by replaying through the ingestion pipeline:

```bash
matyan-client restore-reingest BACKUP_PATH [--backend-url URL] [--frontier-url URL] [--skip-entities] [--skip-blobs] [--dry-run]
```

**Convert TensorBoard** — Convert TensorBoard event logs to a Matyan backup archive (requires `convert` extra):

```bash
matyan-client convert tensorboard INPUT_DIR OUTPUT_PATH [--experiment NAME] [--compress] [--workers N]
```

---

## Links

- [Documentation](https://4gt-104.github.io/matyan-core/)
- [Repository](https://github.com/4gt-104/matyan-core)
- [SDK API reference](https://4gt-104.github.io/matyan-core/) (Run, Repo, objects, adapters)
- License: Apache-2.0
