openrunner-sdk 2.37.1__tar.gz → 2.37.4__tar.gz

{openrunner_sdk-2.37.1 → openrunner_sdk-2.37.4}/.gitignore

@@ -237,3 +237,7 @@ data/
 # MkDocs build output
 /site/
 .claude/worktrees/
+
+# Never commit DB dumps / backups (may contain prod user data)
+*.sql
+backup_*

{openrunner_sdk-2.37.1 → openrunner_sdk-2.37.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrunner-sdk
-Version: 2.37.1
+Version: 2.37.4
 Summary: OpenRunner SDK - W&B-compatible ML experiment tracking client
 Project-URL: Homepage, https://github.com/jqueguiner/openrunner
 Project-URL: Repository, https://github.com/jqueguiner/openrunner

{openrunner_sdk-2.37.1 → openrunner_sdk-2.37.4}/openrunner/__init__.py

@@ -30,6 +30,10 @@ Public API:
     openrunner.alert        -> Send an alert for the active run
     openrunner.log_artifact -> Upload an artifact
     openrunner.use_artifact -> Download an artifact (cached)
+    openrunner.push         -> Publish a model/artifact in one call (HF push_to_hub)
+    openrunner.pull         -> Download a model/artifact in one call (HF from_pretrained)
+    openrunner.load_model   -> Pull + unpickle a Model (or return the local dir)
+    openrunner.list_files   -> List file paths in an artifact version
     openrunner.sweep        -> Create a hyperparameter sweep
     openrunner.agent        -> Run a sweep agent loop
     openrunner.launch       -> Create a remote execution job
@@ -92,9 +96,9 @@ from openrunner.datasets import (
     create_dataset,
     dataset_info,
     index_dataset,
+    iter_rows,
     list_datasets,
     link_project,
-    list_files,
     load_dataset,
     add_derivation,
     push_dataset,
@@ -177,7 +181,7 @@ launch.from_run = _launch_from_run  # type: ignore[attr-defined]
 # openrunner.trace.patch_openai() syntax
 trace.patch_openai = _patch_openai  # type: ignore[attr-defined]
 
-__version__ = "2.37.1"
+__version__ = "2.37.4"
 
 logger = logging.getLogger("openrunner")
 
@@ -936,6 +940,24 @@ def get_model_card(name: str) -> str | None:
         return None
 
 
+# --- README aliases -------------------------------------------------------
+# Artifacts are untyped file buckets; each carries a README.md, which is
+# stored as the artifact's model card (``card_markdown``). ``set_readme`` /
+# ``get_readme`` are thin aliases over ``set_model_card`` / ``get_model_card``
+# for callers who think of it as a README rather than a "model card".
+
+def set_readme(name: str, readme: str) -> dict[str, Any] | None:
+    """Set the README (model card) on an artifact by name. Alias of
+    :func:`set_model_card`. Never raises."""
+    return set_model_card(name, readme)
+
+
+def get_readme(name: str) -> str | None:
+    """Return the README (card_markdown) for an artifact by name. Alias of
+    :func:`get_model_card`. Never raises."""
+    return get_model_card(name)
+
+
 def use_artifact(
     name: str, version: int | None = None, alias: str | None = None
 ) -> Path | None:
@@ -962,6 +984,304 @@ def use_artifact(
         return None
 
 
+# ---------------------------------------------------------------------------
+# HuggingFace-style one-liner ergonomics: push / pull / load_model / list_files
+# ---------------------------------------------------------------------------
+
+
+def _split_name(name: str, project: str | None) -> tuple[str, str | None]:
+    """Split a ``"project/name"`` (or ``"org/project/name"``) reference.
+
+    Accepts either the combined ``"project/name"`` form or a bare ``name``
+    plus an explicit ``project=`` argument. The project part may itself be an
+    ``"org/project"`` reference (which ``init()`` requires).
+
+    Returns ``(artifact_name, project_or_None)``.
+
+    Examples:
+        _split_name("gladia/my-proj/my-model", None) -> ("my-model", "gladia/my-proj")
+        _split_name("my-proj/my-model", None)        -> ("my-model", "my-proj")
+        _split_name("my-model", "gladia/my-proj")    -> ("my-model", "gladia/my-proj")
+    """
+    if "/" in name and project is None:
+        proj, _, artifact = name.rpartition("/")
+        return artifact, (proj or None)
+    return name, project
+
+
+def _ensure_run(project: str | None) -> "Run | None":
+    """Return the active run, auto-initializing one if none exists.
+
+    Mirrors how ``model.Model`` resolves a run: reuse ``_active_run`` if set,
+    otherwise create one with ``init(project=...)``. Never double-creates.
+    """
+    if _active_run is not None:
+        return _active_run
+    return init(project=project, save_code=False)
+
+
+def push(
+    path: str,
+    name: str,
+    *,
+    aliases: list[str] | None = None,
+    description: str | None = None,
+    card: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    project: str | None = None,
+) -> dict[str, Any] | None:
+    """Publish a model/artifact in one call (HuggingFace ``push_to_hub`` style).
+
+    Uploads the file OR directory at ``path`` as an artifact named ``name``.
+    Auto-initializes a run if none is active (reusing the active run otherwise).
+
+    Args:
+        path: Path to a file or directory to upload.
+        name: Artifact name — either ``"project/name"`` or a bare ``name`` with
+            ``project=`` supplied.
+        aliases: Optional aliases to tag the version (e.g. ``["production"]``).
+        description: Optional artifact description.
+        card: Optional markdown model card / README set on the artifact after
+            upload (via :func:`set_model_card`).
+        metadata: Optional artifact metadata dict.
+        project: Project (``"org/project"``) when ``name`` is bare.
+
+    Returns:
+        The created version info dict, or None on failure.
+
+    Example::
+
+        openrunner.push("model.safetensors", "gladia/my-project/my-model",
+                        aliases=["production"], card=open("README.md").read())
+    """
+    try:
+        artifact_name, proj = _split_name(name, project)
+        run = _ensure_run(proj)
+        if run is None:
+            logger.warning("openrunner.push(): could not resolve/create a run")
+            return None
+        result = run.log_model(
+            path,
+            name=artifact_name,
+            aliases=aliases,
+            description=description,
+            metadata=metadata,
+        )
+        if result is not None and card:
+            try:
+                run.set_model_card(artifact_name, card)
+            except Exception as e:  # noqa: BLE001
+                logger.warning("openrunner.push(): set_model_card failed: %s", e)
+        return result
+    except Exception as e:  # noqa: BLE001
+        logger.warning("openrunner.push() failed: %s", e)
+        return None
+
+
+def pull(
+    name: str,
+    *,
+    revision: int | str | None = None,
+    filename: str | None = None,
+    local_dir: str | None = None,
+    project: str | None = None,
+) -> str | None:
+    """Download a model/artifact in one call (HuggingFace ``from_pretrained`` style).
+
+    Auto-initializes a run if none is active (read-only use still needs a run
+    context today).
+
+    Args:
+        name: Artifact name — ``"project/name"`` or bare ``name`` with ``project=``.
+        revision: A version int OR an alias string (e.g. ``"production"``,
+            ``"latest"``). Ints map to ``version=``; strings map to ``alias=``.
+        filename: If given, return the path to just this one file within the
+            version (the whole version is still fetched).
+        local_dir: If given, download into this directory instead of the cache.
+        project: Project (``"org/project"``) when ``name`` is bare.
+
+    Returns:
+        The local directory path (or, when ``filename`` is set, the path to that
+        file), or None on failure.
+
+    Example::
+
+        path = openrunner.pull("gladia/my-project/my-model", revision="production")
+    """
+    try:
+        from pathlib import Path
+
+        artifact_name, proj = _split_name(name, project)
+        run = _ensure_run(proj)
+        if run is None:
+            logger.warning("openrunner.pull(): could not resolve/create a run")
+            return None
+
+        version: int | None = None
+        alias: str | None = None
+        if isinstance(revision, bool):  # guard: bool is an int subclass
+            revision = None
+        if isinstance(revision, int):
+            version = revision
+        elif isinstance(revision, str):
+            alias = revision
+
+        if local_dir is not None:
+            local_path = run.use_model(
+                artifact_name, version=version, alias=alias, dest_dir=local_dir
+            )
+        else:
+            result = run.use_artifact(artifact_name, version=version, alias=alias)
+            local_path = str(result) if result is not None else None
+
+        if local_path is None:
+            return None
+
+        if filename:
+            candidate = Path(local_path) / filename
+            if candidate.exists():
+                return str(candidate)
+            # Fall back to a basename match anywhere in the tree.
+            for p in Path(local_path).rglob("*"):
+                if p.is_file() and p.name == filename:
+                    return str(p)
+            logger.warning("openrunner.pull(): file %r not found in %s", filename, local_path)
+            return None
+
+        return local_path
+    except Exception as e:  # noqa: BLE001
+        logger.warning("openrunner.pull() failed: %s", e)
+        return None
+
+
+def load_model(
+    name: str,
+    *,
+    revision: int | str | None = None,
+    project: str | None = None,
+) -> "Any":
+    """Load a model in one call. Thin wrapper over :func:`pull`.
+
+    If the pulled artifact looks like a pickled :class:`~openrunner.model.Model`
+    (a single ``.pkl`` / ``model.pkl``), it is deserialized via
+    ``Model.load``. Otherwise the local directory path is returned.
+
+    Args:
+        name: Artifact name — ``"project/name"`` or bare ``name`` with ``project=``.
+        revision: Version int or alias string.
+        project: Project (``"org/project"``) when ``name`` is bare.
+
+    Returns:
+        A :class:`~openrunner.model.Model` instance if the artifact is a
+        pickled model, else the local directory path (str), or None on failure.
+
+    Example::
+
+        m = openrunner.load_model("gladia/my-project/my-model", revision="production")
+    """
+    try:
+        from pathlib import Path
+
+        local_path = pull(name, revision=revision, project=project)
+        if local_path is None:
+            return None
+
+        p = Path(local_path)
+        pkl = None
+        if p.is_dir():
+            candidate = p / "model.pkl"
+            if candidate.exists():
+                pkl = candidate
+            else:
+                pkls = list(p.glob("*.pkl"))
+                if len(pkls) == 1:
+                    pkl = pkls[0]
+        elif p.suffix == ".pkl":
+            pkl = p
+
+        if pkl is not None:
+            artifact_name, proj = _split_name(name, project)
+            version = revision if isinstance(revision, int) and not isinstance(revision, bool) else None
+            loaded = Model.load(artifact_name, version=version, project=proj)
+            if loaded is not None:
+                return loaded
+            # Fall back to a direct unpickle if Model.load couldn't resolve it.
+            try:
+                import pickle
+                with open(pkl, "rb") as f:
+                    return pickle.load(f)
+            except Exception as e:  # noqa: BLE001
+                logger.warning("openrunner.load_model(): unpickle failed: %s", e)
+
+        return local_path
+    except Exception as e:  # noqa: BLE001
+        logger.warning("openrunner.load_model() failed: %s", e)
+        return None
+
+
+def list_files(
+    name: str,
+    *,
+    revision: int | str | None = None,
+    project: str | None = None,
+) -> list[str]:
+    """Return the file paths in an artifact version. Never raises.
+
+    Args:
+        name: Artifact name — ``"project/name"`` or bare ``name`` with ``project=``.
+        revision: Version int or alias string (default: latest).
+        project: Project (``"org/project"``) when ``name`` is bare.
+
+    Returns:
+        A list of file paths in the version (empty list on failure).
+
+    Example::
+
+        openrunner.list_files("gladia/my-project/my-model", revision="production")
+    """
+    try:
+        artifact_name, proj = _split_name(name, project)
+        run = _ensure_run(proj)
+        if run is None:
+            logger.warning("openrunner.list_files(): could not resolve/create a run")
+            return []
+
+        version: int | None = None
+        alias: str | None = None
+        if isinstance(revision, bool):
+            revision = None
+        if isinstance(revision, int):
+            version = revision
+        elif isinstance(revision, str):
+            alias = revision
+
+        info = run._client.use_artifact(run.id, artifact_name, version=version, alias=alias)
+        if not info:
+            return []
+
+        # Prefer the version's file listing if a version_id is available.
+        version_id = info.get("version_id")
+        if version_id:
+            files = run._client.list_artifact_files(str(version_id))
+            paths = [
+                f.get("name") or f.get("path")
+                for f in files
+                if (f.get("name") or f.get("path"))
+            ]
+            if paths:
+                return [str(p) for p in paths]
+
+        # Fall back to the file names embedded in the use-artifact response.
+        return [
+            str(f.get("name") or f.get("path"))
+            for f in info.get("files", [])
+            if (f.get("name") or f.get("path"))
+        ]
+    except Exception as e:  # noqa: BLE001
+        logger.warning("openrunner.list_files() failed: %s", e)
+        return []
+
+
 def should_stop() -> bool:
     """Check if the server has requested the active run to stop.
 

openrunner_sdk-2.37.4/openrunner/_safepath.py

@@ -0,0 +1,33 @@
+"""Path-containment helper — the server controls artifact/dataset file names, so
+a name like ``../../.ssh/authorized_keys`` or an absolute path must never escape
+the download directory (would be arbitrary file write == RCE on the user's box)."""
+from pathlib import Path
+
+
+def safe_join(base, rel: str) -> Path:
+    """Return ``base/rel`` resolved, guaranteeing it stays under ``base``.
+    Raises ValueError if ``rel`` is absolute or traverses outside ``base``."""
+    base_p = Path(base).resolve()
+    target = (base_p / str(rel)).resolve()
+    if target != base_p and base_p not in target.parents:
+        raise ValueError(f"unsafe path escapes destination: {rel!r}")
+    return target
+
+
+def safe_extractall(tar, path) -> None:
+    """Extract a tarball with zip-slip protection on ALL Python versions
+    (``filter='data'`` only exists on 3.12+; a malicious member with ``..`` or an
+    absolute path or a link would otherwise write outside ``path``)."""
+    import sys
+
+    if sys.version_info >= (3, 12):
+        tar.extractall(path=path, filter="data")
+        return
+    base = Path(path).resolve()
+    for m in tar.getmembers():
+        target = (base / m.name).resolve()
+        if target != base and base not in target.parents:
+            raise ValueError(f"unsafe tar member escapes destination: {m.name!r}")
+        if m.issym() or m.islnk():
+            raise ValueError(f"refusing tar link member: {m.name!r}")
+    tar.extractall(path=path)