sagea-cursus 0.1.0__tar.gz

sagea_cursus-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: sagea-cursus
+Version: 0.1.0
+Summary: Cursus experiment-tracking SDK — barebones, self-hostable wandb-style init/log/finish.
+Author: SAGEA Labs
+License: SAGEA Noncommercial License 1.0 (see LICENSE in repo root)
+Project-URL: Homepage, https://github.com/sagea-ai/cursus
+Classifier: License :: Other/Proprietary License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# sagea-cursus — Cursus Python SDK
+
+Distribution name is `sagea-cursus` because `cursus` is taken on PyPI by an
+unrelated SageMaker tool. The product is still branded "Cursus".
+
+```bash
+pip install sagea-cursus
+export CURSUS_API_KEY="cursus_..."          # from <server>/<org>/settings/keys
+export CURSUS_BASE_URL="https://cursus.example.com"  # omit for localhost:3000
+```
+
+Full reference: [`docs/sdk.md`](../docs/sdk.md).
+Runnable scripts: [`examples/`](./examples/) (need a live server + key).
+
+## Basic training loop
+
+Credentials come from the environment above, or explicitly per call
+(handy for multi-server scripts — never commit real keys to git):
+
+```python
+import sagea_cursus as cursus
+
+run = cursus.init(
+    project="demo",
+    config={"lr": 1e-4, "arch": "mlp"},
+    api_key="cursus_...",  # or CURSUS_API_KEY
+    base_url="https://cursus.example.com",  # or CURSUS_BASE_URL
+)
+try:
+    for step in range(100):
+        loss = 1.0 / (step + 1)
+        cursus.log({"train/loss": loss}, step=step)
+        if step % 10 == 0:
+            cursus.log({"train/loss": loss, "eval/acc": step / 100}, step=step)
+    cursus.finish()
+except Exception:
+    cursus.finish("crashed")
+    raise
+```
+
+## Images, artifacts, and mid-run config
+
+```python
+import sagea_cursus as cursus
+
+run = cursus.init(project="vision", config={"backbone": "resnet50"})
+for epoch in range(10):
+    train_one_epoch(...)
+    cursus.log({"train/loss": 0.4 / (epoch + 1)}, step=epoch)
+    cursus.log_image("val/samples", f"preds_epoch{epoch}.png", step=epoch)
+    if epoch == 5:
+        cursus.config.update({"lr": 1e-5})  # synced back, debounced
+cursus.log_artifact("resnet50", "runs/best.pt", type="model", description="best val acc")
+cursus.finish()
+```
+
+## Group projects and named runs
+
+```python
+import sagea_cursus as cursus
+
+# Log inside a group project (you must belong to the group).
+run = cursus.init(project="detection", group="vision-team", name="baseline-a", tags=["v2-data"])
+print("view at:", run.url)
+cursus.log({"map50": 0.61}, step=1)
+cursus.finish()
+```
+
+## Sweep worker (grid/random)
+
+```python
+import sagea_cursus as cursus
+
+sweep = cursus.create_sweep(
+    "demo",
+    {"lr": {"min": 1e-5, "max": 1e-1, "scale": "log"}, "batch": {"values": [16, 32]}},
+    name="lr-search",
+)
+while (trial := cursus.next_trial(sweep["id"])) is not None:
+    run = cursus.init(
+        project="demo",
+        config=trial["config"],
+        name=f"sweep-{trial['trial']}",
+        sweep_id=trial["sweep_id"],
+    )
+    try:
+        train(trial["config"])
+        cursus.finish()
+    except Exception:
+        cursus.finish("crashed")
+        raise
+```
+
+## Reliability contract
+
+`init()` may raise (missing key, version skew). Everything else degrades
+to warnings: dead servers cost you points, never a crashed training job.
+Always `finish()` in a `finally` — unflushed points and heartbeats die
+with the process, and the run stays `RUNNING` until staleness flips it.

sagea_cursus-0.1.0/README.md

@@ -0,0 +1,99 @@
+# sagea-cursus — Cursus Python SDK
+
+Distribution name is `sagea-cursus` because `cursus` is taken on PyPI by an
+unrelated SageMaker tool. The product is still branded "Cursus".
+
+```bash
+pip install sagea-cursus
+export CURSUS_API_KEY="cursus_..."          # from <server>/<org>/settings/keys
+export CURSUS_BASE_URL="https://cursus.example.com"  # omit for localhost:3000
+```
+
+Full reference: [`docs/sdk.md`](../docs/sdk.md).
+Runnable scripts: [`examples/`](./examples/) (need a live server + key).
+
+## Basic training loop
+
+Credentials come from the environment above, or explicitly per call
+(handy for multi-server scripts — never commit real keys to git):
+
+```python
+import sagea_cursus as cursus
+
+run = cursus.init(
+    project="demo",
+    config={"lr": 1e-4, "arch": "mlp"},
+    api_key="cursus_...",  # or CURSUS_API_KEY
+    base_url="https://cursus.example.com",  # or CURSUS_BASE_URL
+)
+try:
+    for step in range(100):
+        loss = 1.0 / (step + 1)
+        cursus.log({"train/loss": loss}, step=step)
+        if step % 10 == 0:
+            cursus.log({"train/loss": loss, "eval/acc": step / 100}, step=step)
+    cursus.finish()
+except Exception:
+    cursus.finish("crashed")
+    raise
+```
+
+## Images, artifacts, and mid-run config
+
+```python
+import sagea_cursus as cursus
+
+run = cursus.init(project="vision", config={"backbone": "resnet50"})
+for epoch in range(10):
+    train_one_epoch(...)
+    cursus.log({"train/loss": 0.4 / (epoch + 1)}, step=epoch)
+    cursus.log_image("val/samples", f"preds_epoch{epoch}.png", step=epoch)
+    if epoch == 5:
+        cursus.config.update({"lr": 1e-5})  # synced back, debounced
+cursus.log_artifact("resnet50", "runs/best.pt", type="model", description="best val acc")
+cursus.finish()
+```
+
+## Group projects and named runs
+
+```python
+import sagea_cursus as cursus
+
+# Log inside a group project (you must belong to the group).
+run = cursus.init(project="detection", group="vision-team", name="baseline-a", tags=["v2-data"])
+print("view at:", run.url)
+cursus.log({"map50": 0.61}, step=1)
+cursus.finish()
+```
+
+## Sweep worker (grid/random)
+
+```python
+import sagea_cursus as cursus
+
+sweep = cursus.create_sweep(
+    "demo",
+    {"lr": {"min": 1e-5, "max": 1e-1, "scale": "log"}, "batch": {"values": [16, 32]}},
+    name="lr-search",
+)
+while (trial := cursus.next_trial(sweep["id"])) is not None:
+    run = cursus.init(
+        project="demo",
+        config=trial["config"],
+        name=f"sweep-{trial['trial']}",
+        sweep_id=trial["sweep_id"],
+    )
+    try:
+        train(trial["config"])
+        cursus.finish()
+    except Exception:
+        cursus.finish("crashed")
+        raise
+```
+
+## Reliability contract
+
+`init()` may raise (missing key, version skew). Everything else degrades
+to warnings: dead servers cost you points, never a crashed training job.
+Always `finish()` in a `finally` — unflushed points and heartbeats die
+with the process, and the run stays `RUNNING` until staleness flips it.

sagea_cursus-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sagea-cursus"
+version = "0.1.0"
+description = "Cursus experiment-tracking SDK — barebones, self-hostable wandb-style init/log/finish."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "SAGEA Noncommercial License 1.0 (see LICENSE in repo root)" }
+classifiers = ["License :: Other/Proprietary License"]
+authors = [{ name = "SAGEA Labs" }]
+# Hard dependency: requests only. No optional-dependency creep — numpy/PIL
+# are lazy optional imports, never install requirements.
+dependencies = ["requests>=2.31"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://github.com/sagea-ai/cursus"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sagea_cursus*"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: talks to a real local server (opt-in, needs RUN_CURSUS_INTEGRATION=1)",
+]

sagea_cursus-0.1.0/sagea_cursus/__init__.py

@@ -0,0 +1,251 @@
+"""Public SDK surface: init, log, finish, log_artifact, log_image, config.
+
+``__all__`` enforces the minimal contract — everything else is
+underscore-prefixed and private.
+"""
+
+from __future__ import annotations
+
+import warnings
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from ._client import CursusClient
+from ._media import MAX_BYTES as _MAX_IMAGE_BYTES
+from ._media import encode_image
+from ._run import Run, _clear_current, _get_current, _set_current
+
+__all__ = [
+    "config",
+    "create_sweep",
+    "finish",
+    "init",
+    "log",
+    "log_artifact",
+    "log_image",
+    "next_trial",
+]
+
+config: dict[str, Any] = {}
+
+
+def init(
+    project: str,
+    config: dict[str, Any] | None = None,
+    name: str | None = None,
+    tags: list[str] | None = None,
+    group: str | None = None,
+    sweep_id: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Run:
+    """Create a run on the server and set the module-level singleton.
+
+    Reads the API key from ``api_key`` > ``CURSUS_API_KEY`` env >
+    ``~/.cursus/config``. Fails loudly on version mismatch or missing key —
+    init is the one place raising is acceptable; log/finish never raise.
+
+    Pass ``group="slug"`` to log into a project inside that group (the
+    project is resolved or created there; you must belong to the group).
+    Omit it for org-wide projects visible to every member.
+
+    Example:
+        import sagea_cursus as cursus
+        run = cursus.init(project="demo", config={"lr": 1e-4})
+        cursus.log({"train/loss": 0.4}, step=1)
+        cursus.finish()
+    """
+    client = CursusClient(api_key=api_key, base_url=base_url)
+    if not client.api_key:
+        raise RuntimeError(
+            "Missing Cursus API key. Set CURSUS_API_KEY, pass api_key=..., "
+            "or write ~/.cursus/config."
+        )
+    client.check_version()
+    prev = _get_current()
+    if prev is not None:
+        warnings.warn("cursus: init() called twice; finishing previous run.")
+        try:
+            prev.finish()
+        except Exception:  # noqa: BLE001,S110 — previous run must not break init
+            pass
+    payload = client.create_run(
+        project=project,
+        name=name,
+        config=config or {},
+        tags=tags or [],
+        group=group,
+        sweep_id=sweep_id,
+    )
+    run = Run(
+        client=client,
+        run_id=str(payload["run_id"]),
+        name=str(payload.get("name", "")),
+        url=str(payload.get("url", "")),
+        config=dict(config or {}),
+    )
+    _set_current(run)
+    globals()["config"] = run.config
+    return run
+
+
+def log(data: dict[str, float], step: int | None = None) -> None:
+    """Log a dict of scalars. Warns + drops on failure; never raises."""
+    run = _get_current()
+    if run is None:
+        warnings.warn("cursus: log() called before init(); ignoring.")
+        return
+    run.log(data, step=step)
+
+
+def finish(status: str = "finished") -> None:
+    """Flush + mark the current run finished. Never raises."""
+    run = _get_current()
+    if run is None:
+        return
+    try:
+        run.finish(status=status)
+    finally:
+        _clear_current()
+
+
+def log_artifact(
+    name: str,
+    paths: str | PathLike[str] | list[str | PathLike[str]],
+    type: str = "model",
+    description: str = "",
+) -> dict[str, Any] | None:
+    """Attach files to the current run as a new artifact version.
+
+    Example:
+        cursus.log_artifact("yolov8m", "runs/train/weights/best.pt",
+                            type="model", description="map50: 0.61")
+
+    Warns + skips on failure (missing files, network); never raises into
+    user code. Returns the created version payload, or None when skipped.
+    """
+    run = _get_current()
+    if run is None:
+        warnings.warn("cursus: log_artifact() called before init(); ignoring.")
+        return None
+    if isinstance(paths, (str, PathLike)):
+        paths = [paths]
+    files: list[tuple[str, bytes]] = []
+    for p in paths:
+        try:
+            content = Path(p).read_bytes()
+        except OSError as exc:
+            warnings.warn(f"cursus: log_artifact() skipping unreadable {p}: {exc}")
+            continue
+        files.append((Path(p).name, content))
+    if not files:
+        warnings.warn("cursus: log_artifact() found no readable files; skipping.")
+        return None
+    try:
+        # Same-package access to the run's client (the one funnel).
+        return run._client.create_artifact_version(
+            name=name,
+            files=files,
+            run_id=run.id,
+            artifact_type=type,
+            description=description,
+        )
+    except Exception as exc:  # noqa: BLE001 — never crash training
+        warnings.warn(f"cursus: log_artifact() failed (dropped): {exc}")
+        return None
+
+
+def log_image(
+    key: str,
+    image: str | PathLike[str] | bytes | Any,
+    step: int | None = None,
+) -> dict[str, Any] | None:
+    """Log one image at a step. Bytes go direct to object storage via a
+    presigned URL (no boto — plain requests PUT); the server only signs.
+
+    ``image`` is a file path, raw PNG/JPEG/WEBP bytes, a PIL Image, or a
+    numpy array (last two need pillow installed). Never raises into user
+    code: bad inputs, oversize files (>5 MB), and network failures warn
+    and drop. Returns the completed media payload, or None when skipped.
+
+    Example:
+        cursus.log_image("val/samples", "pred_epoch3.png", step=3)
+    """
+    run = _get_current()
+    if run is None:
+        warnings.warn("cursus: log_image() called before init(); ignoring.")
+        return None
+    if step is None:
+        warnings.warn("cursus: log_image() without step; using 0.")
+        step = 0
+    try:
+        data, mime = encode_image(image)
+    except (OSError, ValueError, TypeError) as exc:
+        warnings.warn(f"cursus: log_image() skipping bad input: {exc}")
+        return None
+    if len(data) > _MAX_IMAGE_BYTES:
+        warnings.warn(f"cursus: log_image() exceeds the 5 MB cap ({len(data)} bytes); skipping.")
+        return None
+    try:
+        ticket = run._client.request_upload_url(run.id, key, int(step), mime, len(data))
+        resp = requests.put(
+            ticket["url"],
+            data=data,
+            headers={"Content-Type": mime},
+            timeout=120.0,
+        )
+        resp.raise_for_status()
+        return run._client.complete_upload(run.id, ticket["mediaId"])
+    except Exception as exc:  # noqa: BLE001 — never crash training
+        warnings.warn(f"cursus: log_image() failed (dropped): {exc}")
+        return None
+
+
+def _sweep_client(api_key: str | None, base_url: str | None) -> CursusClient:
+    client = CursusClient(api_key=api_key, base_url=base_url)
+    if not client.api_key:
+        raise RuntimeError(
+            "Missing Cursus API key. Set CURSUS_API_KEY, pass api_key=..., "
+            "or write ~/.cursus/config."
+        )
+    client.check_version()
+    return client
+
+
+def create_sweep(
+    project: str,
+    space: dict[str, Any],
+    name: str | None = None,
+    method: str = "random",
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> dict[str, Any]:
+    """Create a sweep and return it (including ``id``).
+
+    ``space`` maps names to ``{"values": [...]}`` (choice) or
+    ``{"min": .., "max": .., "scale": "linear"|"log"}`` (random only).
+    May raise like ``init()`` — sweeps are control calls, not logging.
+    """
+    client = _sweep_client(api_key, base_url)
+    return client.create_sweep(
+        project=project,
+        name=name or f"sweep-{project}",
+        method=method.upper(),
+        space=space,
+    )
+
+
+def next_trial(
+    sweep_id: str,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> dict[str, Any] | None:
+    """Claim the next trial config, or None when the sweep is exhausted
+    (grid done, or sweep finished/cancelled). May raise on transport
+    errors — retry or abort the worker loop as you see fit.
+    """
+    client = _sweep_client(api_key, base_url)
+    return client.next_trial(sweep_id)

sagea_cursus-0.1.0/sagea_cursus/_batching.py

@@ -0,0 +1,88 @@
+"""Background flush queue — batching logic, unit-testable with a fake client.
+
+Flush every 5s or every 50 points (whichever first); the server
+does one bulk insert per batch. Plain ``threading`` queue + timer — no
+asyncio, so this works in every training script including ones without an
+event loop.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import warnings
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+FLUSH_INTERVAL_S = 5.0
+FLUSH_MAX_POINTS = 50
+# Bounded retries on network failure: warn + drop, never raise into user code
+# — the single most important SDK reliability property.
+MAX_RETRIES = 3
+
+
+def _utcnow_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class Batcher:
+    """Collects points and flushes them in the background via ``send``."""
+
+    def __init__(
+        self,
+        send: Callable[[list[dict[str, Any]]], None],
+        flush_interval: float = FLUSH_INTERVAL_S,
+        max_points: int = FLUSH_MAX_POINTS,
+        max_retries: int = MAX_RETRIES,
+    ) -> None:
+        self._send = send
+        self._flush_interval = flush_interval
+        self._max_points = max_points
+        self._max_retries = max_retries
+        self._buf: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._loop, name="cursus-flush", daemon=True)
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def enqueue(self, points: list[dict[str, Any]]) -> None:
+        should_flush = False
+        with self._lock:
+            self._buf.extend(points)
+            should_flush = len(self._buf) >= self._max_points
+        if should_flush:
+            self.flush()
+
+    def flush(self) -> None:
+        with self._lock:
+            batch, self._buf = self._buf, []
+        if not batch:
+            return
+        last_exc: Exception | None = None
+        for _ in range(self._max_retries):
+            try:
+                self._send(batch)
+                return
+            except Exception as exc:  # noqa: BLE001 — must never propagate
+                last_exc = exc
+                time.sleep(0.2)
+        warnings.warn(
+            f"cursus: dropped {len(batch)} metric point(s) after "
+            f"{self._max_retries} retries: {last_exc}",
+            stacklevel=3,
+        )
+
+    def close(self) -> None:
+        self._stop.set()
+        self.flush()
+        if self._thread.is_alive():
+            self._thread.join(timeout=5)
+
+    def _loop(self) -> None:
+        while not self._stop.wait(self._flush_interval):
+            try:
+                self.flush()
+            except Exception:  # noqa: BLE001,S112 — background thread never dies
+                continue