Metadata-Version: 2.5
Name: runpeek-sdk
Version: 0.8.0
Summary: Runpeek: watch your Python jobs and tqdm progress bars live from any browser or phone.
Project-URL: Homepage, https://runpeek.app
Project-URL: Documentation, https://runpeek.app/docs
Project-URL: Pricing, https://runpeek.app/pricing
Author-email: Bitgate <kevin@bitgate.com>
License: MIT
Keywords: ml,monitoring,progress,progress-bar,runpeek,tqdm,training
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Requires-Dist: tqdm>=4.60
Description-Content-Type: text/markdown

# Runpeek

Stream your tqdm progress bars to any browser, realtime. Zero config, anonymous by default.

```bash
pip install runpeek-sdk
```

```python
from runpeek import tqdm

for epoch in tqdm(range(epochs)):
    train_one_epoch()

# prints: runpeek ▶ https://runpeek.app/b/<uuid>  (expires 30 min after the last update; 'runpeek login' saves runs)
```

Or leave your code completely untouched:

```python
import runpeek
runpeek.patch()  # every tqdm bar in this process now streams
```

Open the printed URL on your phone. Done.

## Runs

```python
runpeek.start_run("train-resnet")  # one link for every bar in this process
```

```bash
runpeek run -- python train.py --epochs 30
```

A run shows the process lifecycle next to its bars and closes with the real exit code. `runpeek run` wraps any command, streams its stdout/stderr and patches tqdm in the child without code changes.

## Alerts

```python
runpeek.start_run("train-resnet")
runpeek.notify("https://discord.com/api/webhooks/...")  # finished or failed
runpeek.notify("https://hooks.slack.com/services/...", events=("failed",), stall_after_minutes=15)
```

Discord and Slack webhooks get a formatted message, any other URL receives the raw JSON event. `stall_after_minutes` (1 to 1440) also alerts when the run goes silent that long. `notify()` needs an active run and returns whether the webhook was registered. `RUNPEEK_NOTIFY` (comma-separated URLs) registers webhooks for every run, `runpeek run` included.

## Save runs to your dashboard

```bash
runpeek login    # approve once in the browser
runpeek whoami   # the account your runs are saved to
```

Once logged in, every script that shows a bar is saved as a run named after the script, next to your `start_run()` and `runpeek run` runs. On servers and CI, set `RUNPEEK_TOKEN` instead (create a token on the dashboard's Setup page). `runpeek logout` removes the saved login.

Notebooks, IPython and the Python REPL are the exception: bars there stay anonymous, so an idle kernel never becomes a run.
To save an experiment from a notebook, call `runpeek.start_run("my-experiment")` before the loop and `runpeek.end_run()` when it's done.

Free accounts keep 7 days of history, [Pro](https://runpeek.app/pricing) ($9/mo) keeps a year. Over the monthly saved-run limit a run still streams live, it just isn't saved.

## Notes

- Bars are addressed by unguessable UUIDs. No account needed, logging in is optional.
- Heartbeats are throttled (~0.75s) and sent from a daemon thread; your loop never blocks on the network, and send failures never raise into your code.
- An unsaved bar or run expires 30 minutes after its last heartbeat.

## Config (all optional)

```python
import runpeek
runpeek.setup(endpoint="https://runpeek.app", link_base="https://runpeek.link", min_interval=0.75, token="rpk_...")
```

Env vars: `RUNPEEK_TOKEN`, `RUNPEEK_ENDPOINT`, `RUNPEEK_LINK_BASE`, `RUNPEEK_MIN_INTERVAL`, `RUNPEEK_NOTIFY`, `RUNPEEK_DISABLE=1`.
Printed view links use the link base; it defaults to the endpoint itself when unset, so
self-hosted setups keep working. A token is picked from `setup(token=...)`, then `RUNPEEK_TOKEN`,
then the login saved by `runpeek login` (`~/.config/runpeek/config.json`).

Previously published as `tqdm-live`; `pip install tqdm-live` now installs this package.
