runq-sdk 0.5.0__tar.gz

runq_sdk-0.5.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: runq-sdk
+Version: 0.5.0
+Summary: Lab GPU scheduler — in-task Python SDK
+Author: runq contributors
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: wandb
+Requires-Dist: wandb>=0.15; extra == "wandb"
+
+# runq Python SDK
+
+In-task SDK for the [runq](../../README.md) GPU scheduler.
+
+## Install
+
+From the repo root:
+
+```sh
+pip install -e ./sdk/python
+```
+
+Optional extras:
+
+```sh
+pip install -e "./sdk/python[wandb]"   # auto wandb integration
+pip install -e "./sdk/python[dev]"     # for pytest
+```
+
+## Quick start
+
+```python
+import runq
+
+ctx = runq.context()
+runq.log_metric("loss", 0.42, step=epoch)
+```
+
+See `demo/l2c/stage2_sdk_design.md` for the full API design.
+
+## Three modes
+
+Detected automatically at `runq.context()`:
+
+- `daemon` — running under a runq daemon (`RUNQ_TASK_ID` + `RUNQ_SOCKET_PATH` set)
+- `no_daemon` — running on HPC compute node (`RUNQ_TASK_ID` set, no socket / `RUNQ_NO_DAEMON=1`)
+- `manual` — running outside runq (no `RUNQ_TASK_ID`); useful for local debugging
+
+`ctx.mode` exposes which mode is active.
+
+## Stage 2 status
+
+This is incremental — Tier A first, Tier B/C as we go.
+
+- [x] **Step 1**: package skeleton + `context()` + tri-mode + `log_metric`
+- [ ] Step 2: `transport.py` (unix socket HTTP client)
+- [ ] Step 3: `safe_save` core (path resolution + TOCTOU + freeze)
+- [ ] Step 4: `safe_save` decorator + size walker
+- [ ] Step 5: `safe_save` manifest + keep_last_n / keep_best
+- [ ] Step 6: `report` + `Decision` + `@early_stop`
+- [ ] Step 7: YAML early_stop policies
+- [ ] Step 8: `loop` + `@epoch` + `@log_group`
+- [ ] Step 9: wandb integration (L3)
+- [ ] Step 10: daemon-side preflight (Go side, parallel track)

runq_sdk-0.5.0/README.md

@@ -0,0 +1,54 @@
+# runq Python SDK
+
+In-task SDK for the [runq](../../README.md) GPU scheduler.
+
+## Install
+
+From the repo root:
+
+```sh
+pip install -e ./sdk/python
+```
+
+Optional extras:
+
+```sh
+pip install -e "./sdk/python[wandb]"   # auto wandb integration
+pip install -e "./sdk/python[dev]"     # for pytest
+```
+
+## Quick start
+
+```python
+import runq
+
+ctx = runq.context()
+runq.log_metric("loss", 0.42, step=epoch)
+```
+
+See `demo/l2c/stage2_sdk_design.md` for the full API design.
+
+## Three modes
+
+Detected automatically at `runq.context()`:
+
+- `daemon` — running under a runq daemon (`RUNQ_TASK_ID` + `RUNQ_SOCKET_PATH` set)
+- `no_daemon` — running on HPC compute node (`RUNQ_TASK_ID` set, no socket / `RUNQ_NO_DAEMON=1`)
+- `manual` — running outside runq (no `RUNQ_TASK_ID`); useful for local debugging
+
+`ctx.mode` exposes which mode is active.
+
+## Stage 2 status
+
+This is incremental — Tier A first, Tier B/C as we go.
+
+- [x] **Step 1**: package skeleton + `context()` + tri-mode + `log_metric`
+- [ ] Step 2: `transport.py` (unix socket HTTP client)
+- [ ] Step 3: `safe_save` core (path resolution + TOCTOU + freeze)
+- [ ] Step 4: `safe_save` decorator + size walker
+- [ ] Step 5: `safe_save` manifest + keep_last_n / keep_best
+- [ ] Step 6: `report` + `Decision` + `@early_stop`
+- [ ] Step 7: YAML early_stop policies
+- [ ] Step 8: `loop` + `@epoch` + `@log_group`
+- [ ] Step 9: wandb integration (L3)
+- [ ] Step 10: daemon-side preflight (Go side, parallel track)

runq_sdk-0.5.0/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "runq-sdk"
+version = "0.5.0"
+description = "Lab GPU scheduler — in-task Python SDK"
+readme = "README.md"
+# 3.10 floor: matches PyTorch's current support window and is widely
+# deployed in lab conda envs. 3.9 EOL is Oct 2025 — not worth carrying.
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "runq contributors"}]
+
+# httpx for HTTP-over-unix-socket. Pulls in httpcore + h11 + anyio +
+# idna + sniffio — about 1 MB total. Lab user envs almost always have
+# these already (transitively via wandb / transformers / fastapi).
+# Worth the dep for cleaner code than hand-rolled framing.
+#
+# torch is intentionally NOT pinned — safe_save's size estimator
+# imports it lazily, missing torch falls back to size_hint requirement.
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.6",
+]
+# Convenience: pip install -e ".[wandb]" pulls wandb for users who want
+# the L3 mirror integration. Core SDK still works without it.
+wandb = [
+    "wandb>=0.15",
+]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["runq*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+# Match the package's Python floor. Older targets force a more
+# conservative subset (e.g. no `X | Y` types, no `int | None` PEP 604).
+target-version = "py310"
+line-length = 100
+
+# Source roots that ruff walks. ``examples/`` is included so demos
+# follow the same hygiene as the SDK itself.
+src = ["runq", "tests", "examples"]
+
+# Built-in pyc caches + editor backups never need to be linted.
+extend-exclude = ["__pycache__", "*.pyc", ".venv", "build", "dist"]
+
+[tool.ruff.lint]
+# Selected rule sets. Wider than pyflakes-only (E/F) but narrower than
+# "all" — keeping bloat out and signal high. Rationale per group:
+#   E,W     — pycodestyle (style errors / warnings; the baseline)
+#   F       — pyflakes (real bugs: undefined names, unused imports)
+#   I       — isort (consistent import order — small but constant value)
+#   B       — flake8-bugbear (mutable defaults, except-pass, etc.)
+#   UP      — pyupgrade (modernizations for the target Python)
+#   SIM     — flake8-simplify (collapse-able patterns)
+#   RUF     — ruff-native rules (RUF100 for unused noqa, etc.)
+select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF"]
+
+# Global ignores:
+# - RUF002/RUF003: em-dashes (—) and other Unicode look-alikes in
+#   docstrings + comments. We use em-dashes intentionally throughout
+#   the SDK; the ASCII fallback ("--") would regress readability.
+# - SIM105: rewrite ``try: ... except X: pass`` as
+#   ``with contextlib.suppress(X): ...``. The try/except/pass pattern
+#   is idiomatic and arguably clearer at the call site (exception
+#   class is right there, no extra import); collapse-to-suppress
+#   doesn't add signal.
+ignore = ["RUF002", "RUF003", "SIM105"]
+
+# Per-file relaxations:
+# - tests can have unused imports (pytest plugins, fixtures defined in
+#   conftest), `assert` patterns, and longer lines for readability.
+# - examples have prose-y comments that may push line length.
+[tool.ruff.lint.per-file-ignores]
+"tests/*"    = ["E501", "F401", "B011"]
+"examples/*" = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["runq"]

runq_sdk-0.5.0/runq/__init__.py

@@ -0,0 +1,90 @@
+"""runq — Lab GPU scheduler SDK (in-task client).
+
+Public API::
+
+    import runq
+
+    ctx = runq.context()
+
+    # Typed params with auto merge from sweep
+    @runq.dataclass(auto_overwrite=True)
+    class Params:
+        lr: float = 0.001
+        batch_size: int = 32
+    cfg = Params()
+
+    # Training loop with auto step + preemption
+    for step in runq.range(100):
+        loss = train(model)
+        runq.log_metric("loss", loss)             # step auto-populated
+        runq.report({"val_loss": evaluate(model)}) # early-stop check
+        runq.safe_save("ckpt.pt", model.state_dict())
+
+    # Resume from latest checkpoint
+    ckpt = runq.latest_checkpoint()
+"""
+
+from ._config import dataclass
+from ._context import Context, ParamDict, context, get_ctx
+from ._events import log_metric
+from ._exceptions import RunqDiskFullError, RunqEarlyStopSignal, RunqError
+from ._loop import log_group, loop
+from ._manifest import best_checkpoint, latest_checkpoint
+from ._policies import convergence, patience, threshold
+from ._range import is_preempted, range
+from ._record import record
+from ._report import Decision, early_stop, report
+from ._safe_save import safe_save
+from ._transport import TransportError
+from . import utils
+
+__all__ = [  # noqa: RUF022
+    # Init + context
+    "Context",
+    "ParamDict",
+    "context",
+    "get_ctx",
+    # Typed parameter dataclass
+    "dataclass",
+    # Training loop
+    "loop",
+    "range",
+    "is_preempted",
+    # Metrics
+    "log_metric",
+    "log_group",
+    # Results (bounded facts, stored in full — see _record.py)
+    "record",
+    # Early stop
+    "report",
+    "early_stop",
+    "Decision",
+    "patience",
+    "threshold",
+    "convergence",
+    # Checkpoint
+    "safe_save",
+    "best_checkpoint",
+    "latest_checkpoint",
+    # Exceptions
+    "RunqError",
+    "RunqDiskFullError",
+    "RunqEarlyStopSignal",
+    "TransportError",
+]
+
+__version__ = "0.5.0"
+
+
+def __getattr__(name: str):
+    """Module-level attribute access for convenience properties."""
+    if name == "preempted":
+        from ._range import is_preempted
+        return is_preempted()
+    if name == "seed":
+        from ._context import get_ctx
+        return get_ctx().seed
+    if name == "params":
+        from ._context import get_ctx
+        return get_ctx().params
+    raise AttributeError(f"module 'runq' has no attribute {name!r}")

runq_sdk-0.5.0/runq/_config.py

@@ -0,0 +1,152 @@
+"""Typed parameter dataclass with automatic runq.params merging.
+
+``@runq.dataclass`` wraps a plain class into a ``dataclasses.dataclass``
+with extras:
+
+- **Pre-check**: all fields must have defaults — caught at class
+  definition time, not at runtime.
+- **Auto-overwrite**: when ``auto_overwrite=True``, matching keys from
+  ``runq.params`` override defaults at instantiation time.
+- **Serialization**: ``to_dict`` / ``to_json`` / ``from_json`` /
+  ``to_yaml`` / ``from_yaml`` out of the box.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from pathlib import Path
+from typing import Any
+
+
+def dataclass(
+    cls=None,
+    *,
+    auto_overwrite: bool = False,
+    strict: bool = False,
+):
+    """Decorator that turns a class into a runq parameter dataclass.
+
+    All fields must have defaults. If ``auto_overwrite`` is True, matching
+    keys from ``runq.params`` override defaults at instantiation time.
+
+    Usage::
+
+        @runq.dataclass(auto_overwrite=True)
+        class MyConfig:
+            lr: float = 0.001
+            batch_size: int = 32
+
+        cfg = MyConfig()       # lr overridden from runq.params if present
+        cfg.to_json("cfg.json")
+    """
+
+    def wrap(cls):
+        # Make it a dataclass if not already
+        if not dataclasses.is_dataclass(cls):
+            cls = dataclasses.dataclass(cls)
+
+        # Pre-check: every field must have a default
+        for f in dataclasses.fields(cls):
+            has_default = (
+                f.default is not dataclasses.MISSING
+                or f.default_factory is not dataclasses.MISSING
+            )
+            if not has_default:
+                raise TypeError(
+                    f"@runq.dataclass: field '{f.name}' has no default. "
+                    "All fields must have defaults so missing params are "
+                    "caught at definition time, not at runtime."
+                )
+
+        # Store options on the class for introspection
+        cls._runq_auto_overwrite = auto_overwrite
+        cls._runq_strict = strict
+
+        # Wrap __init__ for auto_overwrite
+        if auto_overwrite:
+            original_init = cls.__init__
+
+            def new_init(self, *args, **kwargs):
+                original_init(self, *args, **kwargs)
+                _merge_params(self, strict)
+
+            cls.__init__ = new_init
+
+        # Add serialization methods
+        cls.to_dict = _to_dict
+        cls.to_json = _to_json
+        cls.from_json = classmethod(_from_json)
+        cls.to_yaml = _to_yaml
+        cls.from_yaml = classmethod(_from_yaml)
+
+        return cls
+
+    if cls is None:
+        return wrap
+    return wrap(cls)
+
+
+def _merge_params(instance: Any, strict: bool) -> None:
+    """Merge runq.params into the dataclass instance."""
+    from runq._context import get_ctx
+
+    try:
+        ctx = get_ctx()
+    except RuntimeError:
+        return  # no context initialized yet
+
+    fields = {f.name for f in dataclasses.fields(instance)}
+    for key, val in ctx.params.items():
+        if key in fields:
+            setattr(instance, key, val)
+        elif strict:
+            raise AttributeError(
+                f"Param '{key}' from runq.params not found in "
+                f"{type(instance).__name__}. "
+                f"Available fields: {sorted(fields)}. "
+                f"Set strict=False to ignore."
+            )
+        else:
+            continue
+
+
+def _to_dict(self) -> dict[str, Any]:
+    """Convert to plain dict."""
+    return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}
+
+
+def _to_json(self, path: str | Path | None = None, **kwargs) -> str:
+    """Serialize to JSON string. Optionally write to file."""
+    data = self.to_dict()
+    text = json.dumps(data, indent=2, ensure_ascii=False, **kwargs)
+    if path is not None:
+        Path(path).write_text(text, encoding="utf-8")
+    return text
+
+
+def _from_json(cls, path: str | Path) -> Any:
+    """Load from a JSON file."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    known = {f.name for f in dataclasses.fields(cls)}
+    return cls(**{k: v for k, v in data.items() if k in known})
+
+
+def _to_yaml(self, path: str | Path | None = None) -> str:
+    """Serialize to YAML string. Requires pyyaml."""
+    import yaml
+
+    data = self.to_dict()
+    text = yaml.dump(data, default_flow_style=False, allow_unicode=True)
+    if path is not None:
+        Path(path).write_text(text, encoding="utf-8")
+    return text
+
+
+def _from_yaml(cls, path: str | Path) -> Any:
+    """Load from a YAML file. Requires pyyaml."""
+    import yaml
+
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    known = {f.name for f in dataclasses.fields(cls)}
+    return cls(**{k: v for k, v in data.items() if k in known})