expman-server 0.3.4

Web server and dashboard for expman
Documentation

Expman Server

Axum web server with REST API and SSE live streaming for expman-rs.

Overview

The expman-server module provides a lightweight, high-performance web backend built with Axum. It serves both the REST API for retrieving experiment metadata/metrics and the Server-Sent Events (SSE) endpoints for real-time live streaming of experiment updates directly to the web dashboard.

Key Features

  • Live Data Streaming (SSE): Clients receive real-time updates for logs and metrics via Server-Sent Events, removing the need for continuous polling.
  • Embedded Frontend: The compiled web dashboard UI is embedded directly into the binary, simplifying deployment.
  • RESTful API: Provides clean JSON endpoints for querying experiments, runs, artifacts, and historical Parquet metric data.
  • Jupyter Integration: Includes endpoints to automatically spawn pre-configured live Jupyter notebooks analyzing a specific run's data.

Server Usage

You typically do not need to use expman-server directly in your code, as the expman-cli binary wraps it perfectly.

To run the server via the CLI wrapper:

# Starts the server on http://localhost:8000
exp serve ./experiments

API Endpoints Overview

If you wish to interact programmatically with the dashboard's data, the server exposes the following routes under /api:

Experiments & Runs

  • GET /api/experiments: List all registered experiments.
  • GET /api/experiments/:experiment/runs: List all runs for a given experiment. Supports query parameter filtering like ?metrics=loss,accuracy to selectively extract specific scalar tails.
  • GET /api/experiments/:experiment/runs/:run: Retrieve full details (metadata, full config) of a specific run.

Data & Files

  • GET /api/experiments/:experiment/runs/:run/metrics: Fetch historical metric data for a run (parsed from metrics.parquet).
  • GET /api/experiments/:experiment/runs/:run/artifacts: List all files saved in a run's artifacts/ folder.
  • GET /api/experiments/:experiment/runs/:run/artifacts/*path: Download a specific artifact file.

Live SSE Streams

  • GET /api/experiments/:experiment/runs/:run/live: Connect to the Server-Sent Event stream for a specific run. Streams events like LogMessage, MetricsUpdated, and StatusChanged as they happen.

Integrations

  • POST /api/jupyter/spawn: Spawns a Jupyter notebook environment tied to a specific run for live analysis using polars.