vmn-exp-sdk 0.1.0__tar.gz

vmn_exp_sdk-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2026 Pavel Rogovoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vmn_exp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: vmn-exp-sdk
+Version: 0.1.0
+Summary: vmn experiment SDK: record runs and metrics from jobs, git-free
+Author-email: Pavel Rogovoy <p.rogovoy@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/progovoy/vmn
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: PyYAML>=5.4.1
+Requires-Dist: filelock>=3.2.0
+Provides-Extra: s3
+Requires-Dist: boto3; extra == "s3"
+Provides-Extra: sysmetrics
+Requires-Dist: psutil>=5.9; extra == "sysmetrics"
+Dynamic: license-file
+
+# vmn-exp-sdk
+
+The metrics writer of the [vmn](https://github.com/progovoy/vmn) experiment
+platform, for jobs: `start_run()`, `log_metric`/`log_params`/artifacts,
+autologging and framework integrations — with no git and no vmn installed.
+
+```sh
+pip install vmn-exp-sdk          # add [s3] to record to a bucket
+```
+
+```python
+from vmn_exp.sdk import start_run
+
+with start_run("my_app") as run:   # VMN_SNAPSHOT_METADATA + VMN_EXPERIMENT_DIR/BUCKET
+    run.log_metric("loss", 0.12)
+```
+
+Creating runs from a git checkout, the `vmn-exp` CLI and the dashboard live in
+[`vmn-exp`](https://pypi.org/project/vmn-exp/). See
+[docs/sdk.md](https://github.com/progovoy/vmn/blob/master/docs/sdk.md).

vmn_exp_sdk-0.1.0/README.md

@@ -0,0 +1,20 @@
+# vmn-exp-sdk
+
+The metrics writer of the [vmn](https://github.com/progovoy/vmn) experiment
+platform, for jobs: `start_run()`, `log_metric`/`log_params`/artifacts,
+autologging and framework integrations — with no git and no vmn installed.
+
+```sh
+pip install vmn-exp-sdk          # add [s3] to record to a bucket
+```
+
+```python
+from vmn_exp.sdk import start_run
+
+with start_run("my_app") as run:   # VMN_SNAPSHOT_METADATA + VMN_EXPERIMENT_DIR/BUCKET
+    run.log_metric("loss", 0.12)
+```
+
+Creating runs from a git checkout, the `vmn-exp` CLI and the dashboard live in
+[`vmn-exp`](https://pypi.org/project/vmn-exp/). See
+[docs/sdk.md](https://github.com/progovoy/vmn/blob/master/docs/sdk.md).

vmn_exp_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vmn-exp-sdk"
+version = "0.1.0"  # written by `vmn stamp vmn_exp`, shared with vmn-exp
+description = "vmn experiment SDK: record runs and metrics from jobs, git-free"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Pavel Rogovoy", email = "p.rogovoy@gmail.com" }]
+requires-python = ">=3.8"
+dependencies = [
+    "PyYAML>=5.4.1",
+    "filelock>=3.2.0",
+]
+
+[project.optional-dependencies]
+s3 = ["boto3"]
+# GPU metrics also need pynvml, which stays out of every extra: it is useless
+# without a driver and would break installs on CPU-only hosts.
+sysmetrics = ["psutil>=5.9"]
+
+[project.urls]
+Homepage = "https://github.com/progovoy/vmn"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true  # vmn_exp is shared with vmn-exp (PEP 420)

vmn_exp_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vmn_exp_sdk-0.1.0/src/vmn_exp/_base.py

@@ -0,0 +1,101 @@
+"""Helpers the job SDK needs from vmn, copied so vmn-exp-sdk does not depend on
+vmn. tests/test_exp_base.py keeps each copy in step with version_stamp.core."""
+import datetime
+import hashlib
+import logging
+import os
+
+import yaml
+from filelock import FileLock
+
+# The same logger the vmn CLI configures, so both sides share its handlers.
+VMN_LOGGER = logging.getLogger("vmn")
+
+# libyaml's loader is ~10x faster than the pure-Python one, and experiment
+# listings parse one metadata.yml (and one run_state.yml) per run.
+_FAST_SAFE_LOADER = getattr(yaml, "CSafeLoader", yaml.SafeLoader)
+
+_UNSAFE_IN_COMPONENT = ("/", "\\", os.sep, "\0", "..")
+
+
+def ensure_logger():
+    return VMN_LOGGER
+
+
+def yaml_safe_load(stream_or_text):
+    """``yaml.safe_load`` semantics, on the C loader when libyaml is present."""
+    return yaml.load(stream_or_text, Loader=_FAST_SAFE_LOADER)
+
+
+def parse_record_metadata(raw):
+    """A snapshot/experiment record's ``metadata.yml`` dict, or None.
+
+    None for a missing or unparsable file and for legacy ``create_snapshots``
+    verinfo files, which share the tree but carry no ``verstr``.
+    """
+    if not raw:
+        return None
+    try:
+        meta = yaml_safe_load(raw)
+    except yaml.YAMLError:
+        return None
+    return meta if isinstance(meta, dict) and "verstr" in meta else None
+
+
+def valid_path_component(name):
+    """Whether *name* (a verstr, artifact name, ...) stays one path component."""
+    return (
+        bool(name)
+        and name != "."
+        and not any(bad in name for bad in _UNSAFE_IN_COMPONENT)
+    )
+
+
+def valid_app_path(app_name):
+    """Whether *app_name* is a relative path of real components (``root/svc``)."""
+    return bool(app_name) and all(
+        valid_path_component(part) for part in app_name.split("/")
+    )
+
+
+def now_iso():
+    """UTC now as the ``...Z`` ISO string every vmn record is timestamped with."""
+    return (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+
+def sha256_file(abs_path):
+    h = hashlib.sha256()
+    with open(abs_path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 16), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _is_root(path):
+    return os.path.exists(os.path.join(path, ".git")) or os.path.exists(
+        os.path.join(path, ".vmn")
+    )
+
+
+def resolve_root_path():
+    """The nearest directory at or above the working dir holding .git or .vmn."""
+    path = os.path.realpath(
+        os.path.expanduser(os.environ.get("VMN_WORKING_DIR", os.getcwd()))
+    )
+    while not _is_root(path):
+        parent = os.path.realpath(os.path.join(path, ".."))
+        if parent == path:
+            raise RuntimeError("Running from an unmanaged directory")
+        path = parent
+    return path
+
+
+def get_repo_lock(vmn_root_path):
+    """The per-repo FileLock every vmn command takes; ``$VMN_LOCK_FILE_PATH``
+    overrides its path for the whole process."""
+    return FileLock(
+        os.environ.get("VMN_LOCK_FILE_PATH")
+        or os.path.join(vmn_root_path, ".vmn", "vmn.lock")
+    )

vmn_exp_sdk-0.1.0/src/vmn_exp/core/background.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""One background worker that only ever does the newest pending job.
+
+Slow remote writes — the SDK's run-state copy and log sync, ``vmn-exp run``'s
+log sync — must never run on the heartbeat thread: a hung S3 PUT there is a heartbeat that did
+not happen. Both are "catch the remote up" jobs, where a job overtaken by a
+newer one is not worth doing, so pending jobs coalesce into the newest and run
+one at a time, in order.
+"""
+import logging
+import threading
+
+_LOGGER = logging.getLogger(__name__)
+_NOTHING = object()
+
+
+class Coalescing:
+    """Run ``job(item)`` off-thread for the newest submitted *item*."""
+
+    def __init__(self, job, name):
+        self._job = job
+        self._name = name
+        self._cond = threading.Condition()
+        self._pending = _NOTHING
+        self._closed = False
+        self._thread = None
+
+    def submit(self, item=None):
+        with self._cond:
+            self._pending = item
+            self._cond.notify()
+            if self._thread is None:
+                self._thread = threading.Thread(
+                    target=self._loop, name=self._name, daemon=True
+                )
+                self._thread.start()
+
+    def close(self, timeout):
+        """Finish what is pending, then stop. False if that took over *timeout*."""
+        with self._cond:
+            self._closed = True
+            self._cond.notify()
+            thread = self._thread
+        if thread is None:
+            return True
+        thread.join(timeout)
+        return not thread.is_alive()
+
+    def _next(self):
+        """The next item, or ``_NOTHING`` once closed with nothing pending."""
+        with self._cond:
+            while self._pending is _NOTHING and not self._closed:
+                self._cond.wait()
+            item, self._pending = self._pending, _NOTHING
+            return item
+
+    def _loop(self):
+        while True:
+            item = self._next()
+            if item is _NOTHING:
+                return
+            try:
+                self._job(item)
+            except Exception:
+                _LOGGER.debug(f"{self._name} job failed", exc_info=True)

vmn_exp_sdk-0.1.0/src/vmn_exp/core/best_effort.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Running the chores a run's liveness depends on, without ever raising.
+
+Both run recorders — ``vmn-exp run`` supervising a child and the SDK's
+in-process ``Run`` — have steps that must not end the run when they fail: a
+heartbeat write, a remote sync, a final state. A failure there is reported,
+never thrown at the workload.
+"""
+import threading
+
+
+class BestEffort:
+    """Call a step; on failure report it and return None instead of raising.
+
+    *describe(what, exc)* words the report. With *warn_first* the first failure
+    of each step is a warning — the user should learn their heartbeat or sync
+    is failing — and repeats go to debug, so a flapping backend cannot flood
+    the output. Without it every failure is debug-only.
+    """
+
+    def __init__(self, logger, describe, warn_first=True):
+        self._logger = logger
+        self._describe = describe
+        self._warn_first = warn_first
+        self._warned = set()
+        self._lock = threading.Lock()
+
+    def __call__(self, what, fn, *args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except Exception as exc:
+            if self._first_failure(what):
+                self._logger.warning(self._describe(what, exc))
+            self._logger.debug(f"{what} failed", exc_info=True)
+            return None
+
+    def _first_failure(self, what):
+        if not self._warn_first:
+            return False
+        with self._lock:
+            first = what not in self._warned
+            self._warned.add(what)
+        return first
+
+
+def quiet(logger):
+    """A :class:`BestEffort` that only ever logs at debug."""
+    return BestEffort(logger, describe=None, warn_first=False)
+

vmn_exp_sdk-0.1.0/src/vmn_exp/core/env.py

@@ -0,0 +1,331 @@
+"""Stdlib-only environment capture for experiment provenance.
+
+``capture_env()``     -> full dict (python/platform/hostname/packages/cuda/container)
+``scan_packages()``   -> (dict name->version, truncated_flag) scanning sys.path
+``env_summary()``     -> <= 2 KB dict suitable for metadata.yml
+``packages_sha()``    -> stable sha256 over sorted name==version pairs
+``_cuda_info()``      -> reads torch.version.cuda ONLY if torch already loaded
+``_container_info()`` -> image digest from env vars / /.dockerenv presence
+``env_from_interpreter()`` -> probe an external Python exe, parse JSON from stdout
+
+No third-party imports; safe to run as a subprocess script.
+"""
+import hashlib
+import importlib
+import json
+import os
+import platform
+import re
+import socket
+import subprocess
+import sys
+
+_PACKAGE_CAP = 2000
+_PEP503_RE = re.compile(r"[-_.]+")
+
+# Key ML packages shown verbatim in the summary.
+_KEY_PACKAGES = {"torch", "tensorflow", "jax", "numpy", "transformers"}
+
+
+# ---------------------------------------------------------------------------
+# Name normalisation (PEP 503)
+# ---------------------------------------------------------------------------
+
+def _normalize_name(name: str) -> str:
+    return _PEP503_RE.sub("-", name).lower()
+
+
+# ---------------------------------------------------------------------------
+# Metadata file parser
+# ---------------------------------------------------------------------------
+
+def _parse_metadata_file(path: str):
+    """Return (name, version) from a METADATA or PKG-INFO file header section."""
+    name = version = None
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.rstrip("\r\n")
+                if not line:
+                    break
+                if line.startswith("Name:") and name is None:
+                    name = line[5:].strip()
+                elif line.startswith("Version:") and version is None:
+                    version = line[8:].strip()
+                if name and version:
+                    break
+    except OSError:
+        pass
+    return name, version
+
+
+def _parse_dir_stem(stem: str):
+    """Fallback: parse name and version from a dist/egg dir stem like 'numpy-1.24.0'."""
+    m = re.match(r"^(.+?)-(\d[\w.]*)(.*)$", stem)
+    if m:
+        tail = (m.group(2) + m.group(3)).rstrip("-")
+        return m.group(1), tail
+    return stem, "unknown"
+
+
+# ---------------------------------------------------------------------------
+# Package scanning
+# ---------------------------------------------------------------------------
+
+def scan_packages(paths=None):
+    """Scan *paths* (default: sys.path) for dist-info / egg-info records.
+
+    Returns ``(packages, truncated)`` where *packages* maps normalised package
+    names to version strings and *truncated* is ``True`` when the cap was hit.
+    """
+    if paths is None:
+        paths = sys.path
+    packages: dict = {}
+    for base in paths:
+        if not base or not os.path.isdir(base):
+            continue
+        try:
+            entries = os.listdir(base)
+        except OSError:
+            continue
+        for entry in entries:
+            if len(packages) >= _PACKAGE_CAP:
+                return packages, True
+            name = version = None
+            full = os.path.join(base, entry)
+            if entry.endswith(".dist-info"):
+                meta = os.path.join(full, "METADATA")
+                if os.path.isfile(meta):
+                    name, version = _parse_metadata_file(meta)
+                if not name:
+                    name, version = _parse_dir_stem(entry[: -len(".dist-info")])
+            elif entry.endswith(".egg-info"):
+                if os.path.isdir(full):
+                    meta = os.path.join(full, "PKG-INFO")
+                else:
+                    meta = full  # single-file .egg-info
+                if os.path.isfile(meta):
+                    name, version = _parse_metadata_file(meta)
+                if not name:
+                    name, version = _parse_dir_stem(entry[: -len(".egg-info")])
+            if name:
+                norm = _normalize_name(name)
+                packages.setdefault(norm, version or "unknown")
+    return packages, False
+
+
+# ---------------------------------------------------------------------------
+# SHA over package list
+# ---------------------------------------------------------------------------
+
+def packages_sha(packages: dict) -> str:
+    """Return a stable sha256 hex digest over sorted ``name==version`` pairs."""
+    items = sorted(f"{k}=={v}" for k, v in packages.items())
+    return hashlib.sha256("\n".join(items).encode()).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# CUDA info (never imports torch; reads it only if already loaded)
+# ---------------------------------------------------------------------------
+
+def _cuda_info():
+    """Return cuda/driver info dict, or ``None`` if nothing is available."""
+    result: dict = {}
+    torch = sys.modules.get("torch")
+    if torch is not None:
+        try:
+            cuda_ver = torch.version.cuda
+            if cuda_ver is not None:
+                result["torch_cuda"] = cuda_ver
+        except Exception:
+            pass
+
+    pynvml = sys.modules.get("pynvml")
+    if pynvml is None:
+        try:
+            pynvml = importlib.import_module("pynvml")
+        except Exception:
+            pass
+    if pynvml is not None:
+        try:
+            pynvml.nvmlInit()
+            result["driver"] = pynvml.nvmlSystemGetDriverVersion()
+        except Exception:
+            pass
+    return result or None
+
+
+# ---------------------------------------------------------------------------
+# Container / image info (env vars only — never dumps full environ)
+# ---------------------------------------------------------------------------
+
+_DIGEST_ENV_VARS = (
+    "VMN_IMAGE_DIGEST",
+    "IMAGE_DIGEST",
+    "DOCKER_IMAGE_DIGEST",
+    "CONTAINER_IMAGE_DIGEST",
+)
+
+
+def _container_info():
+    """Return container info dict, or ``None`` if no evidence of a container."""
+    result: dict = {}
+    for var in _DIGEST_ENV_VARS:
+        val = os.environ.get(var)
+        if val:
+            result["image_digest"] = val
+            break
+    if os.path.exists("/.dockerenv"):
+        result["in_docker"] = True
+    return result or None
+
+
+# ---------------------------------------------------------------------------
+# Full env capture
+# ---------------------------------------------------------------------------
+
+def capture_env() -> dict:
+    """Return a full environment dict (python/platform/hostname/packages/cuda/container)."""
+    packages, truncated = scan_packages()
+    env: dict = {
+        "python": {
+            "version": platform.python_version(),
+            "implementation": platform.python_implementation(),
+            "executable": sys.executable,
+        },
+        "platform": {
+            "system": platform.system(),
+            "machine": platform.machine(),
+            "release": platform.release(),
+        },
+        "hostname": socket.gethostname(),
+        "packages": packages,
+    }
+    if truncated:
+        env["packages_truncated"] = True
+    cuda = _cuda_info()
+    if cuda:
+        env["cuda"] = cuda
+    container = _container_info()
+    if container:
+        env["container"] = container
+    return env
+
+
+# ---------------------------------------------------------------------------
+# Summary (<= 2 KB)
+# ---------------------------------------------------------------------------
+
+def env_summary(env: dict) -> dict:
+    """Return a compact (<= 2 KB) summary dict suitable for metadata.yml."""
+    packages = env.get("packages", {})
+    key_pkgs = {k: packages[k] for k in _KEY_PACKAGES if k in packages}
+    summary: dict = {
+        "python": env.get("python", {}).get("version"),
+        "platform": "{}/{}".format(
+            env.get("platform", {}).get("system", ""),
+            env.get("platform", {}).get("machine", ""),
+        ),
+        "packages_count": len(packages),
+        "packages_sha": packages_sha(packages),
+    }
+    if key_pkgs:
+        summary["key_packages"] = key_pkgs
+    cuda = env.get("cuda")
+    if cuda:
+        summary["cuda"] = cuda
+    container = env.get("container")
+    if container and container.get("image_digest"):
+        summary["image_digest"] = container["image_digest"]
+    return summary
+
+
+# ---------------------------------------------------------------------------
+# Probe an external interpreter
+# ---------------------------------------------------------------------------
+
+def env_from_interpreter(python_exe: str, timeout: int = 5) -> dict:
+    """Run this module file under *python_exe* with ``-I`` and return the JSON output.
+
+    The child runs in isolated mode so it does not inherit PYTHONPATH or
+    site-packages from the caller.  If the child does not have vmn installed,
+    we still run the raw file (it is stdlib-only and has no imports from vmn).
+    """
+    module_file = os.path.abspath(__file__)
+    result = subprocess.run(
+        [python_exe, "-I", module_file],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"env_from_interpreter failed (exit {result.returncode}): {result.stderr}"
+        )
+    return json.loads(result.stdout)
+
+
+# ---------------------------------------------------------------------------
+# Capture-decision helpers
+# ---------------------------------------------------------------------------
+
+#: Environment variable that opts out of env capture when set to ``0`` or
+#: a falsy string (``false``, ``no``, ``off``).
+CAPTURE_ENV_ENV = "VMN_CAPTURE_ENV"
+
+_OPT_OUT_VALS = frozenset(("0", "false", "False", "no", "off"))
+
+
+def should_capture(explicit, exp_conf=None):
+    """Return True if the environment should be captured.
+
+    Precedence: explicit arg > ``VMN_CAPTURE_ENV`` > conf > True.
+
+    *explicit* controls the override:
+
+    * ``False`` — always skip (overrides env-var and conf).
+    * ``True``  — override conf, but still respect ``VMN_CAPTURE_ENV``.
+    * ``None``  — full opt-out chain (env-var → conf → default True).
+
+    *exp_conf* is the ``experiment:`` section of the app's conf.yml, as a dict.
+    """
+    if explicit is False:
+        return False
+    env_val = os.environ.get(CAPTURE_ENV_ENV)
+    if env_val in _OPT_OUT_VALS:
+        return False
+    if explicit is True:
+        return True  # explicit True overrides conf but env-var already checked
+    # explicit is None: also check conf
+    if exp_conf:
+        conf_val = exp_conf.get("capture_env")
+        if conf_val is not None:
+            return bool(conf_val)
+    return True
+
+
+def capture_env_safe(python_exe=None):
+    """Capture the environment dict; return ``None`` on any failure (never raises).
+
+    When *python_exe* is given the child interpreter is probed via
+    ``env_from_interpreter``; otherwise the current interpreter is captured.
+    """
+    try:
+        if python_exe:
+            return env_from_interpreter(python_exe, timeout=5)
+        return capture_env()
+    except Exception:
+        import logging
+
+        logging.getLogger(__name__).warning(
+            "vmn: could not capture environment for this run"
+        )
+        return None
+
+
+# ---------------------------------------------------------------------------
+# __main__: print JSON for env_from_interpreter / manual use
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    print(json.dumps(capture_env()))