runmonitor 0.2.0__py3-none-any.whl

runmonitor/__init__.py

@@ -0,0 +1,125 @@
+"""
+runmonitor — a lean, local experiment tracker with a live web dashboard.
+Import and go.  Dashboard auto-starts on port 8080.
+"""
+
+import json
+import uuid
+import atexit
+import threading
+import time
+from . import server  # noqa: F401 — starts the daemon
+from . import storage
+
+
+class Run:
+    """A single experiment run.  Created via rm.init()."""
+
+    def __init__(self, run_id: str, project_id: int, name: str | None,
+                 config: dict, total_steps: int | None):
+        self._id = run_id
+        self._project_id = project_id
+        self._name = name
+        self._config = config
+        self._total_steps = total_steps
+        self._finished = False
+        self._sysmon_stop = threading.Event()
+        self._sysmon_thread = None
+        self._start_sysmon()
+        atexit.register(self._on_exit)
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def name(self) -> str | None:
+        return self._name
+
+    def log(self, metrics: dict, step: int) -> None:
+        """Log a dictionary of metric-name → float at a given step."""
+        if self._finished:
+            raise RuntimeError("Cannot log to a finished run.")
+        if not isinstance(metrics, dict):
+            raise TypeError("metrics must be a dict")
+        storage.log_metrics(self._id, metrics, step)
+
+    def save(self, filepath: str) -> dict:
+        """Save an artifact file alongside this run. Returns artifact info dict."""
+        return storage.save_artifact(self._id, filepath)
+
+    def finish(self) -> None:
+        """Mark the run as successfully finished."""
+        if self._finished:
+            return
+        self._stop_sysmon()
+        storage.finish_run(self._id, "finished")
+        self._finished = True
+
+    def fail(self) -> None:
+        """Mark the run as crashed."""
+        if self._finished:
+            return
+        self._stop_sysmon()
+        storage.finish_run(self._id, "crashed")
+        self._finished = True
+
+    # ── system metrics background thread ───────────────────
+
+    def _start_sysmon(self):
+        """Start a daemon thread that logs CPU/RAM every 10 seconds."""
+        def _collect():
+            try:
+                import psutil
+                has_psutil = True
+            except ImportError:
+                has_psutil = False
+
+            last_cpu_sample = None
+            step_counter = 0
+            while not self._sysmon_stop.wait(timeout=10):
+                if not has_psutil:
+                    return
+                step_counter += 1
+                try:
+                    cpu = psutil.cpu_percent(interval=0.1)
+                    mem = psutil.virtual_memory().percent
+                    storage.log_system_metrics(self._id, step_counter, cpu, mem)
+                except Exception:
+                    pass
+
+        self._sysmon_thread = threading.Thread(
+            target=_collect, name="rm-sysmon", daemon=True
+        )
+        self._sysmon_thread.start()
+
+    def _stop_sysmon(self):
+        self._sysmon_stop.set()
+        if self._sysmon_thread:
+            self._sysmon_thread.join(timeout=2)
+
+    def _on_exit(self):
+        """Mark the run as crashed if it exits without finish()/fail()."""
+        if self._finished:
+            return
+        self._stop_sysmon()
+        storage.finish_run(self._id, "crashed")
+        self._finished = True
+
+
+def init(project: str, name: str | None = None, config: dict | None = None,
+         total_steps: int | None = None) -> Run:
+    """
+    Create (or reuse) a project and start a new run.
+
+        import runmonitor as rm
+        run = rm.init("mnist-experiment", config={"lr": 0.001}, total_steps=1000)
+
+    Opens http://localhost:8080 for the live dashboard.
+    """
+    storage.init_db()
+    project_id = storage.create_project(project)
+    run_id = uuid.uuid4().hex[:12]
+    config_json = json.dumps(config or {})
+    storage.create_run(run_id, project_id, name, config_json, total_steps)
+    return Run(run_id, project_id, name, config or {}, total_steps)

runmonitor/__main__.py

@@ -0,0 +1,54 @@
+"""Run the dashboard standalone — no training script needed.
+
+    runmonitor                     # if pip-installed (console script)
+    python -m runmonitor           # from a checkout / vendored copy
+    RUNMONITOR_PORT=9000 runmonitor # choose a port (set before launch)
+
+Importing ``runmonitor`` already auto-starts the dashboard daemon, so this
+just makes sure it's up, opens a browser, and keeps the process alive.
+"""
+import argparse
+import os
+import threading
+import webbrowser
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="runmonitor",
+        description="Live, terminal-styled experiment-tracking dashboard.",
+    )
+    parser.add_argument(
+        "--port", type=int, default=None,
+        help="Preferred port (most reliable via RUNMONITOR_PORT before launch).",
+    )
+    parser.add_argument(
+        "--no-browser", action="store_true",
+        help="Do not open a browser window.",
+    )
+    args = parser.parse_args()
+    if args.port:
+        os.environ.setdefault("RUNMONITOR_PORT", str(args.port))
+
+    from .storage import init_db
+    from . import server
+
+    init_db()
+    server._start_server()  # idempotent — reuses the daemon if already running
+    url = f"http://localhost:{server._port}"
+    print(f"  runmonitor dashboard → {url}")
+    if args.port and args.port != server._port:
+        print(f"  (port {args.port} was unavailable; bound {server._port} instead)")
+    if not args.no_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+    try:
+        threading.Event().wait()  # block forever; Ctrl-C to quit
+    except KeyboardInterrupt:
+        print("\n  bye.")
+
+
+if __name__ == "__main__":
+    main()

runmonitor/server.py

@@ -0,0 +1,163 @@
+"""
+Flask server that auto-starts in a daemon thread on first import.
+Serves the dashboard + JSON API.
+"""
+
+import threading
+import os
+import time
+import socket
+from flask import Flask, jsonify, request, send_from_directory
+
+from . import storage
+
+app = Flask(__name__,
+            template_folder=os.path.join(os.path.dirname(__file__), "templates"),
+            static_folder=os.path.join(os.path.dirname(__file__), "static"))
+app.config["JSONIFY_PRETTYPRINT_REGULAR"] = False
+
+_started = False
+_port = 8080
+
+
+def _find_port(start=None):
+    """Find the first port we can actually bind, starting from `start`.
+
+    Defaults to ``$RUNMONITOR_PORT`` (set before launch) or 8080.
+    """
+    if start is None:
+        try:
+            start = int(os.environ.get("RUNMONITOR_PORT", 8080))
+        except ValueError:
+            start = 8080
+    for p in range(start, start + 100):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("127.0.0.1", p))
+                return p
+            except OSError:
+                continue
+    return start
+
+
+# ── API routes ──────────────────────────────────────────────────
+
+@app.route("/api/projects")
+def api_projects():
+    return jsonify(storage.get_projects())
+
+
+@app.route("/api/runs")
+def api_runs():
+    project = request.args.get("project")
+    return jsonify(storage.get_runs(project))
+
+
+@app.route("/api/runs/<run_id>/config")
+def api_run_config(run_id):
+    row = storage.get_run_config(run_id)
+    if row is None:
+        return jsonify({"error": "not found"}), 404
+    return jsonify(row)
+
+
+@app.route("/api/runs/<run_id>/metrics")
+def api_run_metrics(run_id):
+    key = request.args.get("key")
+    limit = request.args.get("limit")
+    if limit:
+        limit = int(limit)
+    return jsonify(storage.get_metrics(run_id, key, limit))
+
+
+@app.route("/api/runs/<run_id>/metrics/live")
+def api_run_metrics_live(run_id):
+    """Return only metrics with step > `since` for efficient polling."""
+    since = request.args.get("since", 0, type=int)
+    return jsonify(storage.get_metrics(run_id, since=since))
+
+
+@app.route("/api/runs/<run_id>/artifacts")
+def api_run_artifacts(run_id):
+    return jsonify(storage.get_artifacts(run_id))
+
+
+@app.route("/api/runs/<run_id>/system")
+def api_run_system(run_id):
+    return jsonify(storage.get_system_metrics(run_id))
+
+
+@app.route("/api/runs/<run_id>/export")
+def api_run_export(run_id):
+    fmt = request.args.get("format", "json")
+    metrics = storage.get_metrics(run_id)
+    config = storage.get_run_config(run_id)
+
+    if fmt == "csv":
+        import csv
+        import io
+        out = io.StringIO()
+        writer = csv.writer(out)
+        writer.writerow(["step", "key", "value", "timestamp"])
+        for m in metrics:
+            writer.writerow([m["step"], m["key"], m["value"], m["timestamp"]])
+        csv_str = out.getvalue()
+        from flask import Response
+        return Response(
+            csv_str,
+            mimetype="text/csv",
+            headers={"Content-Disposition": f"attachment; filename=run_{run_id}.csv"},
+        )
+    else:
+        return jsonify({
+            "run_id": run_id,
+            "config": config,
+            "metrics": metrics,
+            "artifacts": storage.get_artifacts(run_id),
+            "system_metrics": storage.get_system_metrics(run_id),
+        })
+
+
+@app.route("/api/runs/<run_id>/compare")
+def api_run_compare(run_id):
+    """Return metrics for two runs keyed by the same metric name."""
+    other_id = request.args.get("other")
+    key = request.args.get("key")
+    if not other_id or not key:
+        return jsonify({"error": "need `other` and `key` params"}), 400
+    run_a = storage.get_metrics(run_id, key=key)
+    run_b = storage.get_metrics(other_id, key=key)
+    return jsonify({
+        "run_a": {"id": run_id, "metrics": run_a},
+        "run_b": {"id": other_id, "metrics": run_b},
+    })
+
+
+# ── Dashboard ───────────────────────────────────────────────────
+
+@app.route("/")
+def dashboard():
+    from flask import render_template
+    return render_template("dashboard.html", port=_port)
+
+
+# ── Daemon start ────────────────────────────────────────────────
+
+def _start_server():
+    global _started, _port
+    if _started:
+        return
+    _started = True
+    _port = _find_port()
+
+    def _run():
+        app.run(host="127.0.0.1", port=_port, debug=False, use_reloader=False)
+
+    t = threading.Thread(target=_run, name="runmonitor-server", daemon=True)
+    t.start()
+    time.sleep(0.3)  # give it a moment to bind
+
+
+import os as _os
+if not _os.environ.get("RUNMONITOR_STANDALONE"):
+    _start_server()