pandm 0.1.0__tar.gz

pandm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: web/pnpm-lock.yaml
+      - name: Build dashboard
+        run: pnpm install --frozen-lockfile && pnpm build
+        working-directory: web
+
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - name: Tests
+        run: uv run pytest tests -q
+      - name: Typecheck
+        run: uvx pyright

pandm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+# Publish to PyPI when a version tag is pushed:
+#   git tag v0.1.0 && git push origin v0.1.0
+# Uses PyPI trusted publishing (OIDC) — no API token needed, but the
+# publisher must be registered on pypi.org for this repo + workflow.
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: web/pnpm-lock.yaml
+      - name: Build dashboard
+        run: pnpm install --frozen-lockfile && pnpm build
+        working-directory: web
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Tag must match pyproject version
+        run: |
+          v="$(uv version --short)"
+          if [ "v$v" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME != pyproject version $v"
+            exit 1
+          fi
+
+      - name: Dashboard must be bundled
+        run: test -f src/pandm/static/index.html
+
+      - run: uv build
+
+      - name: Smoke-test wheel
+        run: |
+          uv run --no-project --isolated --with dist/*.whl python -c "import pandm; print(pandm.__version__)"
+          uv run --no-project --isolated --with dist/*.whl pandm version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pandm
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pandm-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# python
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+
+# pandm data
+.pandm/
+
+# web
+web/node_modules/
+src/pandm/static/
+
+# misc
+.DS_Store

pandm-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: pandm
+Version: 0.1.0
+Summary: Beautiful, local-first experiment tracking. A lightweight alternative to wandb / tensorboard.
+Author-email: Jannchie <jannchie@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.29
+Description-Content-Type: text/markdown
+
+# pandm
+
+pandm tracks ML experiments locally. The Python SDK writes metrics and images straight to a `.pandm/` directory next to your code — no account, no daemon, no cloud — and `pandm ui` serves a dashboard to compare runs. Unlike wandb there is nothing to sign up for, and unlike tensorboard the data is plain SQLite + PNG files you can query yourself. The same scripts report to a shared server over HTTP when you set one env var.
+
+![dashboard](docs/screenshot.png)
+
+## Install
+
+```sh
+pip install pandm
+```
+
+## Quick start
+
+```python
+import pandm
+
+run = pandm.init(project="mnist", config={"lr": 1e-3, "batch_size": 64})
+for step in range(1000):
+    loss, acc = train_step()
+    run.log({"train/loss": loss, "train/acc": acc}, step=step)
+    if step % 100 == 0:
+        run.log_image("samples", sample_grid, step=step)  # PIL / numpy / torch / path
+run.finish()
+```
+
+```sh
+pandm ui   # opens http://127.0.0.1:7878
+```
+
+The dashboard overlays selected runs per metric, with smoothing, log scale, step/time axes, an image browser with a step slider, and a config/summary comparison table. It polls while runs are alive, so curves grow during training.
+
+## Usage
+
+`step` is optional (an internal counter is used). Runs end as `finished` or `crashed`: uncaught exceptions are detected via `sys.excepthook` (and the context manager), and hard-killed processes (`kill -9`, OOM) are presumed crashed once their 15s heartbeat goes quiet for 60s — self-healing if the process was merely suspended.
+
+```python
+with pandm.init(project="mnist") as run:
+    run.log({"loss": 0.5})
+```
+
+List or delete runs from the terminal:
+
+```sh
+pandm ls
+pandm delete <run_id>
+```
+
+Data lives in `./.pandm` by default; override with `--dir` or `PANDM_DIR`.
+
+### Cloud mode
+
+Run a server anywhere, then point training scripts at it — no code changes:
+
+```sh
+pandm server --api-key my-secret               # on the server (default port 7878)
+```
+
+```sh
+export PANDM_REMOTE=http://my-host:7878
+export PANDM_API_KEY=my-secret
+python train.py                                 # same script, now reports over HTTP
+```
+
+The API key protects write endpoints only; put the server behind a reverse proxy if reads need auth too. If the server becomes unreachable mid-run, the SDK warns and keeps training: it retries every 30s, replays run creation on recovery, and drops whatever was logged while offline.
+
+## API
+
+| | |
+|---|---|
+| `pandm.init(project, name=None, config=None, *, directory=None, remote=None, api_key=None)` | start a run |
+| `run.log(metrics, step=None)` | log scalar metrics |
+| `run.log_image(key, image, step=None, caption=None)` | log an image |
+| `run.finish(status="finished")` | end the run (also via `atexit`) |
+| `GET /api/docs` | REST API reference on any running server |
+
+## Development
+
+```sh
+uv sync && uv run pytest          # python sdk + server
+cd web && pnpm install && pnpm dev   # dashboard dev server (proxies to :7878)
+pnpm build                        # bundles the dashboard into src/pandm/static
+```
+
+## License
+
+MIT

pandm-0.1.0/README.md

@@ -0,0 +1,87 @@
+# pandm
+
+pandm tracks ML experiments locally. The Python SDK writes metrics and images straight to a `.pandm/` directory next to your code — no account, no daemon, no cloud — and `pandm ui` serves a dashboard to compare runs. Unlike wandb there is nothing to sign up for, and unlike tensorboard the data is plain SQLite + PNG files you can query yourself. The same scripts report to a shared server over HTTP when you set one env var.
+
+![dashboard](docs/screenshot.png)
+
+## Install
+
+```sh
+pip install pandm
+```
+
+## Quick start
+
+```python
+import pandm
+
+run = pandm.init(project="mnist", config={"lr": 1e-3, "batch_size": 64})
+for step in range(1000):
+    loss, acc = train_step()
+    run.log({"train/loss": loss, "train/acc": acc}, step=step)
+    if step % 100 == 0:
+        run.log_image("samples", sample_grid, step=step)  # PIL / numpy / torch / path
+run.finish()
+```
+
+```sh
+pandm ui   # opens http://127.0.0.1:7878
+```
+
+The dashboard overlays selected runs per metric, with smoothing, log scale, step/time axes, an image browser with a step slider, and a config/summary comparison table. It polls while runs are alive, so curves grow during training.
+
+## Usage
+
+`step` is optional (an internal counter is used). Runs end as `finished` or `crashed`: uncaught exceptions are detected via `sys.excepthook` (and the context manager), and hard-killed processes (`kill -9`, OOM) are presumed crashed once their 15s heartbeat goes quiet for 60s — self-healing if the process was merely suspended.
+
+```python
+with pandm.init(project="mnist") as run:
+    run.log({"loss": 0.5})
+```
+
+List or delete runs from the terminal:
+
+```sh
+pandm ls
+pandm delete <run_id>
+```
+
+Data lives in `./.pandm` by default; override with `--dir` or `PANDM_DIR`.
+
+### Cloud mode
+
+Run a server anywhere, then point training scripts at it — no code changes:
+
+```sh
+pandm server --api-key my-secret               # on the server (default port 7878)
+```
+
+```sh
+export PANDM_REMOTE=http://my-host:7878
+export PANDM_API_KEY=my-secret
+python train.py                                 # same script, now reports over HTTP
+```
+
+The API key protects write endpoints only; put the server behind a reverse proxy if reads need auth too. If the server becomes unreachable mid-run, the SDK warns and keeps training: it retries every 30s, replays run creation on recovery, and drops whatever was logged while offline.
+
+## API
+
+| | |
+|---|---|
+| `pandm.init(project, name=None, config=None, *, directory=None, remote=None, api_key=None)` | start a run |
+| `run.log(metrics, step=None)` | log scalar metrics |
+| `run.log_image(key, image, step=None, caption=None)` | log an image |
+| `run.finish(status="finished")` | end the run (also via `atexit`) |
+| `GET /api/docs` | REST API reference on any running server |
+
+## Development
+
+```sh
+uv sync && uv run pytest          # python sdk + server
+cd web && pnpm install && pnpm dev   # dashboard dev server (proxies to :7878)
+pnpm build                        # bundles the dashboard into src/pandm/static
+```
+
+## License
+
+MIT

pandm-0.1.0/examples/train_demo.py

@@ -0,0 +1,70 @@
+"""Simulate a few training runs so the dashboard has something to show.
+
+    uv run python examples/train_demo.py
+    uv run pandm ui
+"""
+
+from __future__ import annotations
+
+import math
+import random
+
+from PIL import Image, ImageDraw, ImageOps
+
+import pandm
+
+PALETTES = [
+    ((24, 26, 60), (139, 149, 246)),
+    ((40, 18, 40), (239, 125, 155)),
+    ((12, 40, 38), (72, 207, 173)),
+    ((45, 30, 12), (245, 163, 95)),
+]
+
+
+def fake_sample(step: int, total: int, palette_idx: int) -> Image.Image:
+    """A 'denoising' image: noise fades out as training progresses."""
+    dark, bright = PALETTES[palette_idx % len(PALETTES)]
+    base = ImageOps.colorize(Image.linear_gradient("L").rotate(45 - palette_idx * 30, expand=False), dark, bright)
+    base = base.resize((256, 256))
+    sigma = 90 * (1 - step / total) + 6
+    noise = ImageOps.colorize(Image.effect_noise((256, 256), sigma), (0, 0, 0), (255, 255, 255))
+    img = Image.blend(base, noise, alpha=max(0.04, 0.8 * (1 - step / total)))
+    draw = ImageDraw.Draw(img)
+    draw.rectangle([8, 224, 116, 246], fill=(0, 0, 0, 160))
+    draw.text((14, 228), f"step {step}", fill=(235, 235, 240))
+    return img
+
+
+def simulate(project: str, name: str, lr: float, bs: int, palette_idx: int, steps: int = 400, seed: int = 0) -> None:
+    rng = random.Random(seed)
+    run = pandm.init(
+        project=project,
+        name=name,
+        config={"lr": lr, "batch_size": bs, "optimizer": "adamw", "model": "resnet18", "seed": seed},
+    )
+    base = 2.0 + rng.uniform(-0.2, 0.4)
+    speed = lr * rng.uniform(800, 1400)
+    for step in range(steps):
+        progress = step / steps
+        loss = base * math.exp(-speed * progress) + 0.08 + rng.gauss(0, 0.02) * (1.2 - progress)
+        acc = 1 - 0.9 * math.exp(-3.5 * progress) + rng.gauss(0, 0.008)
+        lr_t = lr * 0.5 * (1 + math.cos(math.pi * progress))  # cosine schedule
+        run.log({"train/loss": loss, "train/acc": min(acc, 0.999), "lr": lr_t}, step=step)
+        if step % 10 == 0:
+            val_loss = loss + 0.12 + rng.gauss(0, 0.03)
+            run.log({"val/loss": val_loss, "val/acc": min(acc - 0.04 + rng.gauss(0, 0.01), 0.999)}, step=step)
+        if step % 80 == 0 or step == steps - 1:
+            run.log_image("samples", fake_sample(step, steps, palette_idx), step=step, caption=f"epoch {step // 80}")
+    run.finish()
+    print(f"  ✓ {project}/{name}")
+
+
+if __name__ == "__main__":
+    print("simulating runs…")
+    simulate("mnist-diffusion", "baseline", lr=1e-3, bs=64, palette_idx=0, seed=1)
+    simulate("mnist-diffusion", "high-lr", lr=3e-3, bs=64, palette_idx=1, seed=2)
+    simulate("mnist-diffusion", "big-batch", lr=1e-3, bs=256, palette_idx=2, seed=3)
+    simulate("mnist-diffusion", "low-lr", lr=3e-4, bs=64, palette_idx=3, seed=4)
+    simulate("llm-finetune", "lora-r8", lr=2e-4, bs=8, palette_idx=1, steps=300, seed=5)
+    simulate("llm-finetune", "lora-r32", lr=2e-4, bs=8, palette_idx=2, steps=300, seed=6)
+    print("done — run `pandm ui` to view")

pandm-0.1.0/justfile

@@ -0,0 +1,33 @@
+# 列出所有命令
+default:
+    @just --list
+
+# Python 单测
+test:
+    uv run pytest tests -q
+
+# pyright 类型检查
+typecheck:
+    pyright
+
+# 单测 + 类型检查
+check: test typecheck
+
+# 构建前端到 src/pandm/static（打包进 wheel 前必跑）
+web-build:
+    pnpm -C web build
+
+# 前端开发服务器（/api 代理到 127.0.0.1:7878）
+web-dev:
+    pnpm -C web dev
+
+# 生成演示数据
+demo:
+    uv run python examples/train_demo.py
+
+# 启动本地 dashboard
+ui:
+    uv run pandm ui
+
+# 一条龙：建前端 → 造数据 → 开 dashboard
+play: web-build demo ui

pandm-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "pandm"
+version = "0.1.0"
+description = "Beautiful, local-first experiment tracking. A lightweight alternative to wandb / tensorboard."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Jannchie", email = "jannchie@gmail.com" }]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "typer>=0.12",
+    "rich>=13",
+    "pillow>=10",
+    "httpx>=0.27",
+    "python-multipart>=0.0.9",
+]
+
+[project.scripts]
+pandm = "pandm.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+# the built dashboard is gitignored but must ship with the package
+artifacts = ["src/pandm/static/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pandm"]
+
+[dependency-groups]
+dev = ["pytest>=8"]

pandm-0.1.0/pyrightconfig.json

@@ -0,0 +1,4 @@
+{
+  "venvPath": ".",
+  "venv": ".venv"
+}

pandm-0.1.0/src/pandm/__init__.py

@@ -0,0 +1,6 @@
+"""pandm — beautiful, local-first experiment tracking."""
+
+from .sdk import Run, finish, init, log, log_image
+
+__version__ = "0.1.0"
+__all__ = ["init", "log", "log_image", "finish", "Run", "__version__"]

pandm-0.1.0/src/pandm/cli.py

@@ -0,0 +1,135 @@
+"""pandm CLI: `pandm ui` (local dashboard), `pandm server` (cloud mode), `pandm ls`."""
+
+from __future__ import annotations
+
+import threading
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from . import __version__
+from .storage import LocalStore, resolve_dir
+
+app = typer.Typer(
+    help="pandm — beautiful, local-first experiment tracking.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+
+DirOption = typer.Option(None, "--dir", "-d", help="Data directory (default: ./.pandm or $PANDM_DIR).")
+
+
+def _banner(url: str, data_dir: Path, mode: str) -> None:
+    console.print(
+        Panel.fit(
+            f"[bold]pandm[/bold] [dim]v{__version__}[/dim] · {mode}\n\n"
+            f"  [bold cyan]{url}[/bold cyan]\n"
+            f"  [dim]data: {data_dir}[/dim]",
+            border_style="bright_black",
+            padding=(1, 3),
+        )
+    )
+
+
+@app.command()
+def ui(
+    directory: Optional[Path] = DirOption,
+    port: int = typer.Option(7878, "--port", "-p"),
+    host: str = typer.Option("127.0.0.1", "--host"),
+    open_browser: bool = typer.Option(True, "--open/--no-open", help="Open the dashboard in a browser."),
+) -> None:
+    """Start the local dashboard."""
+    import uvicorn
+
+    from .server import create_app
+
+    data_dir = resolve_dir(directory)
+    url = f"http://{host}:{port}"
+    _banner(url, data_dir, "local dashboard")
+    if open_browser:
+        threading.Timer(0.8, webbrowser.open, args=[url]).start()
+    uvicorn.run(create_app(data_dir), host=host, port=port, log_level="warning")
+
+
+@app.command()
+def server(
+    directory: Optional[Path] = DirOption,
+    port: int = typer.Option(7878, "--port", "-p"),
+    host: str = typer.Option("0.0.0.0", "--host"),
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", envvar="PANDM_API_KEY", help="Require x-api-key on write endpoints."
+    ),
+) -> None:
+    """Start a pandm server for cloud deployment (SDKs report via PANDM_REMOTE)."""
+    import uvicorn
+
+    from .server import create_app
+
+    data_dir = resolve_dir(directory)
+    _banner(f"http://{host}:{port}", data_dir, "server mode" + (" · api-key on" if api_key else ""))
+    uvicorn.run(create_app(data_dir, api_key=api_key), host=host, port=port, log_level="info")
+
+
+@app.command("ls")
+def list_runs(
+    project: Optional[str] = typer.Option(None, "--project", "-P"),
+    directory: Optional[Path] = DirOption,
+) -> None:
+    """List runs in the terminal."""
+    store = LocalStore(resolve_dir(directory))
+    runs = store.list_runs(project)
+    if not runs:
+        console.print("[dim]no runs yet — call pandm.init() in your training script[/dim]")
+        return
+
+    import datetime as dt
+
+    status_style = {"running": "bold cyan", "finished": "green", "crashed": "red"}
+    table = Table(box=None, header_style="bold dim", pad_edge=False)
+    for col in ("ID", "NAME", "PROJECT", "STATUS", "CREATED", "DURATION"):
+        table.add_column(col)
+    for run in runs:
+        created = dt.datetime.fromtimestamp(run["created_at"]).strftime("%Y-%m-%d %H:%M")
+        end = run["finished_at"] or run["updated_at"]
+        mins, secs = divmod(int(max(0, end - run["created_at"])), 60)
+        hours, mins = divmod(mins, 60)
+        duration = f"{hours}h{mins:02d}m" if hours else (f"{mins}m{secs:02d}s" if mins else f"{secs}s")
+        table.add_row(
+            f"[dim]{run['id']}[/dim]",
+            run["name"],
+            run["project"],
+            f"[{status_style.get(run['status'], 'white')}]{run['status']}[/]",
+            created,
+            duration,
+        )
+    console.print(table)
+
+
+@app.command()
+def delete(
+    run_id: str,
+    directory: Optional[Path] = DirOption,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Delete a run and its media files."""
+    store = LocalStore(resolve_dir(directory))
+    run = store.get_run(run_id)
+    if run is None:
+        console.print(f"[red]run {run_id} not found[/red]")
+        raise typer.Exit(1)
+    if not yes and not typer.confirm(f"delete run {run['name']} ({run_id})?"):
+        raise typer.Exit(0)
+    store.delete_run(run_id)
+    console.print(f"[dim]deleted {run_id}[/dim]")
+
+
+@app.command()
+def version() -> None:
+    """Print version."""
+    console.print(f"pandm v{__version__}")