lossy 0.1.0__tar.gz

lossy-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.egg-info/
+dist/

lossy-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: lossy
+Version: 0.1.0
+Summary: Two lines to hatch a life - lightweight training-run logger for Lossy (wandb-shaped, zero deps)
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# lossy
+
+Two lines to hatch a life. A tiny, zero-dependency training-run logger that
+feeds the [Lossy](../) pet — a wandb-shaped API with none of the weight.
+
+```python
+import lossy
+
+run = lossy.init(project="my-project", name="run-1", config={"lr": 3e-4})
+for step in range(1, 301):
+    loss = train_step()
+    lossy.log({"train/loss": loss}, step=step)
+run.finish()
+```
+
+## Setup
+
+Pair with the Lossy app (Settings → Lossy SDK) to get your token, then:
+
+```bash
+export LOSSY_TOKEN=lossy_xxxxx        # pairing token from the app
+export LOSSY_API=https://your-deployment.vercel.app   # optional; defaults to prod
+```
+
+No token? Your script still runs exactly as before — the SDK goes inert with
+a single warning. It never raises, never blocks, never slows a training loop:
+logging is a lock-guarded append to a bounded in-memory queue (oldest points
+drop past 10k), a background thread ships batches (≥50 points or every 5s)
+with retries and backoff, and every network failure is a stderr warning, not
+an exception.
+
+## Crash honesty
+
+Uncaught exceptions are reported as `crashed` with an exception summary
+(`sys.excepthook`); a clean `finish()` — or a clean exit without one
+(`atexit`) — reports `finished`. Hard kills (OOM/SIGKILL) can't run hooks;
+the server's liveness sweep covers those.
+
+Ctrl-C currently reports `crashed` too (distinguishable downstream via
+`exitInfo.type == "KeyboardInterrupt"`); a distinct "interrupted" state is a
+recorded product decision for later.
+
+## Environment knobs (mostly for tests)
+
+`LOSSY_TOKEN`, `LOSSY_API`, `LOSSY_FLUSH_INTERVAL`, `LOSSY_BATCH_SIZE`,
+`LOSSY_QUEUE_MAX`, `LOSSY_MAX_RETRIES`, `LOSSY_BACKOFF_BASE`,
+`LOSSY_HTTP_TIMEOUT`, `LOSSY_FINISH_TIMEOUT`.
+
+## Tests
+
+```bash
+cd sdk && uv run --with pytest pytest
+```
+
+Fully offline — an in-process stub server plays the S1 ingest API.

lossy-0.1.0/README.md

@@ -0,0 +1,55 @@
+# lossy
+
+Two lines to hatch a life. A tiny, zero-dependency training-run logger that
+feeds the [Lossy](../) pet — a wandb-shaped API with none of the weight.
+
+```python
+import lossy
+
+run = lossy.init(project="my-project", name="run-1", config={"lr": 3e-4})
+for step in range(1, 301):
+    loss = train_step()
+    lossy.log({"train/loss": loss}, step=step)
+run.finish()
+```
+
+## Setup
+
+Pair with the Lossy app (Settings → Lossy SDK) to get your token, then:
+
+```bash
+export LOSSY_TOKEN=lossy_xxxxx        # pairing token from the app
+export LOSSY_API=https://your-deployment.vercel.app   # optional; defaults to prod
+```
+
+No token? Your script still runs exactly as before — the SDK goes inert with
+a single warning. It never raises, never blocks, never slows a training loop:
+logging is a lock-guarded append to a bounded in-memory queue (oldest points
+drop past 10k), a background thread ships batches (≥50 points or every 5s)
+with retries and backoff, and every network failure is a stderr warning, not
+an exception.
+
+## Crash honesty
+
+Uncaught exceptions are reported as `crashed` with an exception summary
+(`sys.excepthook`); a clean `finish()` — or a clean exit without one
+(`atexit`) — reports `finished`. Hard kills (OOM/SIGKILL) can't run hooks;
+the server's liveness sweep covers those.
+
+Ctrl-C currently reports `crashed` too (distinguishable downstream via
+`exitInfo.type == "KeyboardInterrupt"`); a distinct "interrupted" state is a
+recorded product decision for later.
+
+## Environment knobs (mostly for tests)
+
+`LOSSY_TOKEN`, `LOSSY_API`, `LOSSY_FLUSH_INTERVAL`, `LOSSY_BATCH_SIZE`,
+`LOSSY_QUEUE_MAX`, `LOSSY_MAX_RETRIES`, `LOSSY_BACKOFF_BASE`,
+`LOSSY_HTTP_TIMEOUT`, `LOSSY_FINISH_TIMEOUT`.
+
+## Tests
+
+```bash
+cd sdk && uv run --with pytest pytest
+```
+
+Fully offline — an in-process stub server plays the S1 ingest API.

lossy-0.1.0/lossy/__init__.py

@@ -0,0 +1,44 @@
+"""lossy — two lines to hatch a life.
+
+wandb-shaped module-level ergonomics::
+
+    import lossy
+    run = lossy.init(project="my-proj", name="run-1", config={"lr": 3e-4})
+    lossy.log({"train/loss": loss}, step=step)   # or run.log(...)
+    run.finish()                                  # or lossy.finish()
+
+Auth comes from ``LOSSY_TOKEN`` (pairing token from the app); the endpoint
+from ``LOSSY_API``. Without a token the SDK is inert (one warning) and your
+script runs untouched. See lossy.client for the full behavioral contract.
+"""
+from __future__ import annotations
+
+from .client import Run, _warn_once_global
+
+__version__ = "0.1.0"
+__all__ = ["init", "log", "finish", "run", "Run"]
+
+run: Run | None = None  # the current module-level run, wandb-style
+
+
+def init(project: str | None = None, name: str | None = None,
+         config: dict | None = None, **kwargs) -> Run:
+    """Start a run and make it the module-level current run."""
+    global run
+    run = Run(project=project, name=name, config=config, **kwargs)
+    return run
+
+
+def log(metrics: dict, step: int | None = None) -> None:
+    """Log metrics to the current run. Safe no-op (with a warning) pre-init."""
+    if run is None:
+        _warn_once_global("log-before-init",
+                          "log() called before init(); point ignored")
+        return
+    run.log(metrics, step=step)
+
+
+def finish() -> None:
+    """Finish the current run. Idempotent; safe without init()."""
+    if run is not None:
+        run.finish()

lossy-0.1.0/lossy/client.py

@@ -0,0 +1,359 @@
+"""Lossy SDK core: the Run class and its background shipping worker.
+
+Contract (independence plan, Task S2 — built against S1's endpoint spec):
+
+* Transport: ``POST {LOSSY_API}/api/ingest`` with ``Authorization: Bearer
+  <LOSSY_TOKEN>``; actions ``start`` (returns server ``runId``), ``log``
+  (batch ``points: [{step, metrics, ts}]`` + client ``seq`` for idempotent
+  retries), ``finish`` (``state: finished|crashed`` + optional ``exitInfo``).
+  Bodies stay <= 64KB; oversized batches split.
+* Never stall training: ``log()`` only appends to a bounded queue (oldest
+  dropped past QUEUE_MAX with ONE stderr warning); a daemon thread batches
+  (>= BATCH_SIZE points or every FLUSH_INTERVAL seconds) and ships with
+  exponential-backoff retries. ALL network failures become stderr warnings —
+  never exceptions, so a dead server can't kill a live training job.
+* Crash honesty: sys.excepthook reports ``crashed`` with an exception
+  summary; atexit closes a still-open run as ``finished`` (a clean exit is
+  not a crash — SIGKILL/OOM detection is the server liveness sweep's job).
+  ``Run._finished`` guards against hooks double-firing.
+* No token -> inert run with a single process-wide warning; scripts must run
+  fine unpaired.
+"""
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import sys
+import threading
+import time
+import traceback
+import urllib.error
+import urllib.request
+from collections import deque
+from typing import Any
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, ""))
+    except ValueError:
+        return default
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name, ""))
+    except ValueError:
+        return default
+
+
+DEFAULT_API = "https://lossy-server.vercel.app"  # override with LOSSY_API
+INGEST_PATH = "/api/ingest"
+MAX_BODY_BYTES = 64 * 1024  # S1 rejects bigger bodies
+
+# Timing/size knobs. Env overrides exist so subprocess tests (and unusual
+# deployments) can tune them; in-process tests monkeypatch the module attrs.
+QUEUE_MAX = _env_int("LOSSY_QUEUE_MAX", 10_000)
+BATCH_SIZE = _env_int("LOSSY_BATCH_SIZE", 50)
+FLUSH_INTERVAL = _env_float("LOSSY_FLUSH_INTERVAL", 5.0)
+MAX_RETRIES = _env_int("LOSSY_MAX_RETRIES", 3)
+BACKOFF_BASE = _env_float("LOSSY_BACKOFF_BASE", 0.5)
+HTTP_TIMEOUT = _env_float("LOSSY_HTTP_TIMEOUT", 5.0)
+FINISH_TIMEOUT = _env_float("LOSSY_FINISH_TIMEOUT", 10.0)
+
+_sleep = time.sleep  # indirection so tests can observe backoff delays
+_WARNED_GLOBAL: set[str] = set()  # process-wide once-only warning keys
+
+
+def _warn(msg: str) -> None:
+    print(f"lossy: {msg}", file=sys.stderr)
+
+
+def _warn_once_global(key: str, msg: str) -> None:
+    if key not in _WARNED_GLOBAL:
+        _WARNED_GLOBAL.add(key)
+        _warn(msg)
+
+
+# Recursion depth cap for nested config/metrics values. Deep enough for any
+# sane config; guards against cycles (which would otherwise recurse forever).
+_JSONABLE_MAX_DEPTH = 10
+
+
+def _jsonable(value: Any, _depth: int = 0) -> Any:
+    """Make a value JSON-serializable, preserving structure.
+
+    Dicts/lists/tuples recurse so ``config={"optimizer": {"lr": 1e-3}}``
+    arrives as real nested JSON, not a Python-repr string. Non-serializable
+    leaves (and anything past the depth cap) fall back to ``str``.
+    """
+    if isinstance(value, (int, float, str, bool)) or value is None:
+        return value
+    if _depth >= _JSONABLE_MAX_DEPTH:
+        return str(value)
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v, _depth + 1) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v, _depth + 1) for v in value]
+    return str(value)
+
+
+class Run:
+    """One training run. Create via ``lossy.init()``."""
+
+    def __init__(self, project: str | None = None, name: str | None = None,
+                 config: dict | None = None, *,
+                 _api: str | None = None, _token: str | None = None):
+        self.project = project or "uncategorized"
+        self.name = name or f"run-{int(time.time())}"
+        self.config = {str(k): _jsonable(v) for k, v in (config or {}).items()}
+        self._token = _token if _token is not None else os.environ.get("LOSSY_TOKEN", "")
+        self._api = (_api or os.environ.get("LOSSY_API") or DEFAULT_API).rstrip("/")
+        self._finished = False
+        self._enabled = bool(self._token)
+        if not self._enabled:
+            _warn_once_global(
+                "no-token",
+                "LOSSY_TOKEN is not set — running unpaired; metrics will not "
+                "be sent (your script is unaffected).")
+            return
+
+        # capture knobs at init so a run's behavior is stable for its lifetime
+        self._queue_max = QUEUE_MAX
+        self._batch_size = BATCH_SIZE
+        self._flush_interval = FLUSH_INTERVAL
+        self._max_retries = max(1, MAX_RETRIES)
+        self._backoff_base = BACKOFF_BASE
+        self._http_timeout = HTTP_TIMEOUT
+        self._finish_timeout = FINISH_TIMEOUT
+
+        self._lock = threading.Lock()
+        self._queue: deque[dict] = deque()
+        self._wake = threading.Event()
+        self._closing = False
+        self._finish_state: tuple[str, dict | None] = ("finished", None)
+        self._run_id: str | None = None
+        self._degraded = False  # start failed: swallow everything quietly
+        self._seq = 0
+        self._auto_step = 0
+        self._dropped_warned = False
+        self._warned: set[str] = set()
+
+        self._worker = threading.Thread(
+            target=self._worker_loop, name="lossy-worker", daemon=True)
+        self._worker.start()
+        _install_hooks(self)
+
+    # ------------------------------------------------------------------ API
+
+    def log(self, metrics: dict, step: int | None = None) -> None:
+        """Queue a point. Never blocks, never raises."""
+        try:
+            if not self._enabled or self._finished:
+                return
+            if step is None:
+                self._auto_step += 1
+                step = self._auto_step
+            else:
+                self._auto_step = max(self._auto_step, int(step))
+            point = {
+                "step": int(step),
+                "metrics": {str(k): _jsonable(v) for k, v in metrics.items()},
+                "ts": time.time(),
+            }
+            with self._lock:
+                self._queue.append(point)
+                if len(self._queue) > self._queue_max:
+                    self._queue.popleft()
+                    if not self._dropped_warned:
+                        self._dropped_warned = True
+                        _warn(f"metric queue is full ({self._queue_max}); "
+                              "dropping oldest points (server slow or down?)")
+                ready = len(self._queue) >= self._batch_size
+            if ready:
+                self._wake.set()
+        except Exception as e:  # absolutely never let logging kill training
+            self._warn_once("log-error", f"log() error swallowed: {e!r}")
+
+    def finish(self) -> None:
+        """Flush and mark the run finished. Idempotent, never raises."""
+        self._finish("finished", None)
+
+    # ------------------------------------------------------------ internals
+
+    def _finish(self, state: str, exit_info: dict | None) -> None:
+        if not self._enabled:
+            self._finished = True
+            return
+        if self._finished:
+            return
+        self._finished = True  # set FIRST: atexit/excepthook can't re-enter
+        try:
+            self._finish_state = (state, exit_info)
+            self._closing = True
+            self._wake.set()
+            # bounded join: a dead server must not wedge interpreter exit
+            self._worker.join(timeout=self._finish_timeout)
+            if self._worker.is_alive():
+                self._warn_once("finish-timeout",
+                                "gave up waiting for the upload worker; "
+                                "some points may be lost")
+        except Exception as e:
+            self._warn_once("finish-error", f"finish() error swallowed: {e!r}")
+
+    def _warn_once(self, key: str, msg: str) -> None:
+        if key not in self._warned:
+            self._warned.add(key)
+            _warn(msg)
+
+    def _drain(self) -> list[dict]:
+        with self._lock:
+            points = list(self._queue)
+            self._queue.clear()
+        return points
+
+    def _worker_loop(self) -> None:
+        try:
+            self._start_run()
+            while True:
+                self._wake.wait(timeout=self._flush_interval)
+                self._wake.clear()
+                self._ship(self._drain())
+                if self._closing:
+                    self._ship(self._drain())  # points raced in after drain
+                    break
+            state, exit_info = self._finish_state
+            self._send_finish(state, exit_info)
+        except Exception as e:
+            self._warn_once("worker-error", f"upload worker died: {e!r}; "
+                            "further metrics will be dropped")
+
+    def _start_run(self) -> None:
+        payload = {"action": "start",
+                   "run": {"name": self.name, "project": self.project,
+                           "config": self.config}}
+        resp = self._post(payload)
+        run_id = (resp or {}).get("runId")
+        if not run_id:
+            self._degraded = True
+            self._warn_once("degraded",
+                            "could not register the run with the Lossy "
+                            "server; this run's metrics will be dropped "
+                            "(training is unaffected)")
+        else:
+            self._run_id = run_id
+
+    def _ship(self, points: list[dict]) -> None:
+        if not points or self._degraded:
+            return
+        for chunk in self._split_to_size(points):
+            self._seq += 1
+            payload = {"action": "log", "runId": self._run_id,
+                       "seq": self._seq, "points": chunk}
+            self._post(payload)  # retries inside; give up -> warning
+
+    def _split_to_size(self, points: list[dict]) -> list[list[dict]]:
+        """Split so each serialized body stays under MAX_BODY_BYTES."""
+        envelope = 256  # generous headroom for action/runId/seq fields
+        budget = MAX_BODY_BYTES - envelope
+        if len(_dumps(points)) <= budget:
+            return [points]
+        if len(points) == 1:
+            self._warn_once("giant-point",
+                            "a single log() point exceeds the 64KB ingest "
+                            "limit; dropping it")
+            return []
+        mid = len(points) // 2
+        return (self._split_to_size(points[:mid])
+                + self._split_to_size(points[mid:]))
+
+    def _send_finish(self, state: str, exit_info: dict | None) -> None:
+        if self._degraded or not self._run_id:
+            return
+        payload: dict[str, Any] = {"action": "finish", "runId": self._run_id,
+                                   "state": state}
+        if exit_info:
+            payload["exitInfo"] = exit_info
+        self._post(payload)
+
+    def _post(self, payload: dict) -> dict | None:
+        """POST with exponential-backoff retries. Failure -> warning + None.
+
+        The same body (same seq) is resent on every retry, which is what
+        makes the server-side dedupe work.
+        """
+        body = _dumps(payload)
+        last_err: Exception | None = None
+        for attempt in range(self._max_retries):
+            if attempt:
+                _sleep(self._backoff_base * (2 ** (attempt - 1)))
+            try:
+                req = urllib.request.Request(
+                    self._api + INGEST_PATH, data=body, method="POST",
+                    headers={"Authorization": f"Bearer {self._token}",
+                             "Content-Type": "application/json"})
+                with urllib.request.urlopen(req, timeout=self._http_timeout) as resp:
+                    data = resp.read()
+                try:
+                    return json.loads(data) if data else {}
+                except ValueError:
+                    return {}
+            except urllib.error.HTTPError as e:
+                e.close()  # HTTPError wraps a live response; don't leak it
+                last_err = e
+                if 400 <= e.code < 500 and e.code not in (408, 429):
+                    break  # our bug or bad token: retrying won't help
+            except Exception as e:  # URLError, socket errors, timeouts
+                last_err = e
+        self._warn_once(
+            f"net:{payload.get('action')}",
+            f"could not send '{payload.get('action')}' to {self._api} "
+            f"({last_err}); this batch was dropped, but future batches "
+            "will still be attempted")
+        return None
+
+
+def _dumps(obj: Any) -> bytes:
+    return json.dumps(obj, separators=(",", ":"), default=str).encode()
+
+
+# ------------------------------------------------------- crash-honesty hooks
+
+def _install_hooks(run: Run) -> None:
+    """atexit + sys.excepthook. ``Run._finished`` (set before any network
+    work in ``_finish``) guarantees at most one finish, whatever order the
+    interpreter fires these in."""
+
+    def _on_exit() -> None:
+        # excepthook already handled a crash, or the user finish()ed: no-op.
+        run._finish("finished", None)
+
+    atexit.register(_on_exit)
+
+    prev_hook = sys.excepthook
+
+    def _on_exception(exc_type, exc_value, exc_tb):
+        # Product decision (recorded, not changed here): Ctrl-C reports
+        # `crashed` like any other uncaught exception. Downstream CAN
+        # distinguish it via exitInfo.type == "KeyboardInterrupt"; a
+        # distinct "interrupted" state is deferred for later.
+        try:
+            run._finish("crashed", _exception_summary(exc_type, exc_value, exc_tb))
+        finally:
+            prev_hook(exc_type, exc_value, exc_tb)  # user still sees the traceback
+
+    sys.excepthook = _on_exception
+
+
+def _exception_summary(exc_type, exc_value, exc_tb) -> dict:
+    info = {"type": getattr(exc_type, "__name__", str(exc_type)),
+            "message": str(exc_value)[:500]}
+    try:
+        frames = traceback.extract_tb(exc_tb)
+        if frames:
+            last = frames[-1]
+            info["where"] = f"{os.path.basename(last.filename)}:{last.lineno} in {last.name}"
+    except Exception:
+        pass
+    return info

lossy-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "lossy"
+version = "0.1.0"
+description = "Two lines to hatch a life - lightweight training-run logger for Lossy (wandb-shaped, zero deps)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["lossy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

lossy-0.1.0/tests/conftest.py

@@ -0,0 +1,126 @@
+"""Offline test harness: an in-process stub of the Lossy ingest server.
+
+The SDK is built against the Task S1 contract (POST /api/ingest with
+actions start/log/finish); these tests never touch the real server.
+"""
+import json
+import socket
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+
+class _Handler(BaseHTTPRequestHandler):
+    def do_POST(self):  # noqa: N802 (http.server API)
+        length = int(self.headers.get("Content-Length", 0))
+        raw = self.rfile.read(length)
+        try:
+            body = json.loads(raw)
+        except ValueError:
+            body = None
+        record = {
+            "path": self.path,
+            "headers": {k: v for k, v in self.headers.items()},
+            "body": body,
+            "raw_len": len(raw),
+        }
+        stub = self.server.stub
+        with stub.lock:
+            stub.requests.append(record)
+            fail = stub.fail_remaining > 0
+            if fail:
+                stub.fail_remaining -= 1
+        if fail:
+            self._respond(500, {"error": "injected failure"})
+            return
+        action = (body or {}).get("action")
+        if action == "start":
+            self._respond(200, {"runId": stub.run_id})
+        else:
+            self._respond(200, {"ok": True})
+
+    def _respond(self, code, payload):
+        data = json.dumps(payload).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def log_message(self, *args):  # keep pytest output clean
+        pass
+
+
+class StubServer:
+    def __init__(self):
+        self._httpd = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
+        self._httpd.stub = self
+        self.lock = threading.Lock()
+        self.requests: list[dict] = []
+        self.fail_remaining = 0
+        self.run_id = "lrun-test-1"
+        self._thread = threading.Thread(target=self._httpd.serve_forever, daemon=True)
+        self._thread.start()
+
+    @property
+    def url(self):
+        host, port = self._httpd.server_address
+        return f"http://{host}:{port}"
+
+    def set_failures(self, n):
+        with self.lock:
+            self.fail_remaining = n
+
+    def snapshot(self):
+        with self.lock:
+            return list(self.requests)
+
+    def by_action(self, action):
+        return [r for r in self.snapshot()
+                if r["body"] and r["body"].get("action") == action]
+
+    def wait_for(self, predicate, timeout=5.0):
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            snap = self.snapshot()
+            if predicate(snap):
+                return snap
+            time.sleep(0.02)
+        raise AssertionError(f"stub condition not met within {timeout}s; "
+                             f"saw {len(self.snapshot())} requests")
+
+    def close(self):
+        self._httpd.shutdown()
+        self._httpd.server_close()
+
+
+@pytest.fixture
+def stub():
+    s = StubServer()
+    yield s
+    s.close()
+
+
+@pytest.fixture
+def closed_port():
+    """A localhost port with nothing listening (connection refused fast)."""
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+@pytest.fixture
+def fast(monkeypatch):
+    """Speed up SDK timing knobs so tests run in milliseconds."""
+    from lossy import client
+    monkeypatch.setattr(client, "FLUSH_INTERVAL", 0.05)
+    monkeypatch.setattr(client, "BACKOFF_BASE", 0.01)
+    monkeypatch.setattr(client, "MAX_RETRIES", 3)
+    monkeypatch.setattr(client, "HTTP_TIMEOUT", 2.0)
+    monkeypatch.setattr(client, "FINISH_TIMEOUT", 5.0)
+    monkeypatch.setenv("LOSSY_TOKEN", "lossy_test_token")
+    return client

lossy-0.1.0/tests/test_body_limit.py

@@ -0,0 +1,21 @@
+"""Ingest bodies must stay <=64KB (S1 rate/size limit); big batches split."""
+import lossy
+
+LIMIT = 64 * 1024
+
+
+def test_bodies_stay_under_64kb_and_points_survive_the_split(stub, fast):
+    run = lossy.init(project="p", name="chunky", _api=stub.url)
+    blob = "x" * 600
+    for i in range(200):  # ~120KB of points if sent as one body
+        run.log({"loss": 0.1, "note": blob}, step=i)
+    run.finish()
+
+    logs = stub.by_action("log")
+    assert len(logs) >= 2, "oversized batch should split into multiple bodies"
+    for r in stub.snapshot():
+        assert r["raw_len"] <= LIMIT
+    steps = [p["step"] for r in logs for p in r["body"]["points"]]
+    assert steps == list(range(200))
+    seqs = [r["body"]["seq"] for r in logs]
+    assert len(set(seqs)) == len(seqs), "each shipped body needs its own seq"

lossy-0.1.0/tests/test_crash_hooks.py

@@ -0,0 +1,95 @@
+"""Crash honesty: atexit + sys.excepthook in a REAL interpreter (subprocess).
+
+In-process pytest can't exercise excepthook/atexit truthfully, so these
+spawn `python -c` children pointed at the stub server.
+"""
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+SDK_DIR = str(Path(__file__).resolve().parents[1])
+
+
+def _run_child(code, stub, extra_env=None):
+    env = os.environ.copy()
+    env.update({
+        "PYTHONPATH": SDK_DIR,
+        "LOSSY_TOKEN": "lossy_child_token",
+        "LOSSY_API": stub.url,
+        # fast timing so the child exits quickly
+        "LOSSY_FLUSH_INTERVAL": "0.05",
+        "LOSSY_BACKOFF_BASE": "0.01",
+        "LOSSY_FINISH_TIMEOUT": "5",
+        "LOSSY_HTTP_TIMEOUT": "2",
+    })
+    env.update(extra_env or {})
+    return subprocess.run([sys.executable, "-c", code], env=env,
+                          capture_output=True, text=True, timeout=30)
+
+
+def test_uncaught_exception_reports_crashed_with_summary(stub):
+    proc = _run_child(
+        "import lossy\n"
+        "lossy.init(project='p', name='doomed')\n"
+        "lossy.log({'loss': 1.0}, step=1)\n"
+        "raise RuntimeError('simulated crash for Lossy testing')\n",
+        stub)
+    assert proc.returncode != 0
+    assert "RuntimeError" in proc.stderr  # traceback still reaches the user
+
+    finishes = stub.by_action("finish")
+    assert len(finishes) == 1, "hooks must not double-fire"
+    body = finishes[0]["body"]
+    assert body["state"] == "crashed"
+    assert body["exitInfo"]["type"] == "RuntimeError"
+    assert "simulated crash" in body["exitInfo"]["message"]
+
+
+def test_clean_finish_reports_finished_exactly_once(stub):
+    proc = _run_child(
+        "import lossy\n"
+        "run = lossy.init(project='p', name='clean')\n"
+        "run.log({'loss': 0.5}, step=1)\n"
+        "run.finish()\n",
+        stub)
+    assert proc.returncode == 0
+    finishes = stub.by_action("finish")
+    assert len(finishes) == 1, "atexit must not re-finish after finish()"
+    assert finishes[0]["body"]["state"] == "finished"
+
+
+def test_exit_without_finish_autofinishes_as_finished(stub):
+    # No exception, no finish() call: atexit closes the run honestly as
+    # finished (a clean exit is not a crash; SIGKILL/OOM honesty is the
+    # server liveness sweep's job, per plan S1).
+    proc = _run_child(
+        "import lossy\n"
+        "lossy.init(project='p', name='forgetful')\n"
+        "lossy.log({'loss': 0.5}, step=1)\n",
+        stub)
+    assert proc.returncode == 0
+    finishes = stub.by_action("finish")
+    assert len(finishes) == 1
+    assert finishes[0]["body"]["state"] == "finished"
+
+
+def test_crash_with_server_down_still_exits_promptly(closed_port):
+    env = os.environ.copy()
+    env.update({
+        "PYTHONPATH": SDK_DIR,
+        "LOSSY_TOKEN": "t",
+        "LOSSY_API": f"http://127.0.0.1:{closed_port}",
+        "LOSSY_FLUSH_INTERVAL": "0.05",
+        "LOSSY_BACKOFF_BASE": "0.01",
+        "LOSSY_FINISH_TIMEOUT": "3",
+        "LOSSY_HTTP_TIMEOUT": "1",
+    })
+    proc = subprocess.run(
+        [sys.executable, "-c",
+         "import lossy\n"
+         "lossy.init(project='p', name='offline-crash')\n"
+         "raise ValueError('boom')\n"],
+        env=env, capture_output=True, text=True, timeout=20)
+    assert proc.returncode != 0
+    assert "ValueError" in proc.stderr

lossy-0.1.0/tests/test_lifecycle.py

@@ -0,0 +1,111 @@
+"""start/log/finish lifecycle, auth header, batching triggers."""
+import lossy
+
+
+def test_start_log_finish_lifecycle(stub, fast):
+    run = lossy.init(project="proj", name="lifecycle", config={"lr": 3e-4},
+                     _api=stub.url)
+    run.log({"train/loss": 1.5}, step=1)
+    run.log({"train/loss": 1.2}, step=2)
+    run.finish()
+
+    starts = stub.by_action("start")
+    assert len(starts) == 1
+    body = starts[0]["body"]
+    assert body["run"]["name"] == "lifecycle"
+    assert body["run"]["project"] == "proj"
+    assert body["run"]["config"]["lr"] == 3e-4
+
+    logs = stub.by_action("log")
+    assert logs, "log batch never arrived"
+    points = [p for r in logs for p in r["body"]["points"]]
+    assert [p["step"] for p in points] == [1, 2]
+    assert points[0]["metrics"]["train/loss"] == 1.5
+    assert all("ts" in p for p in points)
+    assert all(r["body"]["runId"] == stub.run_id for r in logs)
+
+    finishes = stub.by_action("finish")
+    assert len(finishes) == 1
+    assert finishes[0]["body"]["state"] == "finished"
+    assert finishes[0]["body"]["runId"] == stub.run_id
+
+
+def test_nested_config_survives_as_real_json(stub, fast):
+    class Opt:
+        def __repr__(self):
+            return "<Opt adam>"
+
+    run = lossy.init(
+        project="p", name="nested", _api=stub.url,
+        config={"optimizer": {"lr": 1e-3, "betas": [0.9, 0.999]},
+                "obj": Opt()})
+    run.finish()
+    cfg = stub.by_action("start")[0]["body"]["run"]["config"]
+    # nested dicts/lists arrive as real JSON, not a Python-repr string
+    assert cfg["optimizer"] == {"lr": 1e-3, "betas": [0.9, 0.999]}
+    # a non-serializable leaf falls back to str
+    assert cfg["obj"] == "<Opt adam>"
+
+
+def test_jsonable_depth_cap_guards_against_cycles():
+    import json
+    from lossy.client import _jsonable, _JSONABLE_MAX_DEPTH
+    d: dict = {}
+    d["self"] = d  # would recurse forever without the cap
+    out = _jsonable(d)
+    json.dumps(out)  # cycle broken -> serializable
+    depth = 0
+    while isinstance(out, dict):
+        out = out["self"]
+        depth += 1
+    assert isinstance(out, str)
+    assert depth == _JSONABLE_MAX_DEPTH
+
+
+def test_bearer_token_header_on_every_request(stub, fast, monkeypatch):
+    monkeypatch.setenv("LOSSY_TOKEN", "lossy_sekrit")
+    run = lossy.init(project="p", name="auth", _api=stub.url)
+    run.log({"a": 1})
+    run.finish()
+    snap = stub.snapshot()
+    assert snap
+    for r in snap:
+        assert r["headers"].get("Authorization") == "Bearer lossy_sekrit"
+        assert r["path"] == "/api/ingest"
+
+
+def test_batch_of_50_flushes_before_interval(stub, fast, monkeypatch):
+    from lossy import client
+    monkeypatch.setattr(client, "FLUSH_INTERVAL", 60.0)  # only size can trigger
+    run = lossy.init(project="p", name="batch50", _api=stub.url)
+    for i in range(50):
+        run.log({"loss": i * 0.1}, step=i)
+    stub.wait_for(lambda snap: any(
+        r["body"] and r["body"].get("action") == "log" for r in snap), timeout=3.0)
+    run.finish()
+
+
+def test_small_batch_flushes_on_interval(stub, fast):
+    run = lossy.init(project="p", name="timeflush", _api=stub.url)
+    run.log({"loss": 0.5}, step=1)
+    stub.wait_for(lambda snap: any(
+        r["body"] and r["body"].get("action") == "log" for r in snap), timeout=3.0)
+    run.finish()
+
+
+def test_auto_step_increments_when_omitted(stub, fast):
+    run = lossy.init(project="p", name="autostep", _api=stub.url)
+    run.log({"a": 1})
+    run.log({"a": 2})
+    run.finish()
+    points = [p for r in stub.by_action("log") for p in r["body"]["points"]]
+    assert [p["step"] for p in points] == [1, 2]
+
+
+def test_module_level_log_and_finish(stub, fast):
+    lossy.init(project="p", name="module-api", _api=stub.url)
+    lossy.log({"loss": 0.9}, step=7)
+    lossy.finish()
+    points = [p for r in stub.by_action("log") for p in r["body"]["points"]]
+    assert points and points[0]["step"] == 7
+    assert len(stub.by_action("finish")) == 1

lossy-0.1.0/tests/test_offline.py

@@ -0,0 +1,47 @@
+"""Offline-server resilience and the no-token no-op mode.
+
+The product contract: importing/using lossy must NEVER break or stall a
+training script — server down, token missing, whatever.
+"""
+import time
+
+import lossy
+
+
+def test_training_completes_with_server_down(fast, closed_port, capsys):
+    api = f"http://127.0.0.1:{closed_port}"
+    t0 = time.monotonic()
+    run = lossy.init(project="p", name="offline", _api=api)
+    for i in range(200):
+        run.log({"loss": 1.0 / (i + 1)}, step=i)
+    run.finish()
+    assert time.monotonic() - t0 < 5.0, "offline run must not stall training"
+    err = capsys.readouterr().err
+    assert "lossy" in err  # failures surface as warnings...
+    # ...and never as exceptions (reaching this line is the assertion)
+
+
+def test_no_token_is_inert_with_single_warning(monkeypatch, capsys):
+    monkeypatch.delenv("LOSSY_TOKEN", raising=False)
+    from lossy import client
+    client._WARNED_GLOBAL.discard("no-token")
+    run = lossy.init(project="p", name="untethered")
+    for i in range(10):
+        run.log({"loss": i})
+    run.finish()
+    lossy.finish()  # module-level double-finish is safe too
+    err = capsys.readouterr().err
+    assert err.count("LOSSY_TOKEN") == 1, err
+
+    # second init in the same process stays quiet
+    run2 = lossy.init(project="p", name="untethered2")
+    run2.log({"a": 1})
+    run2.finish()
+    assert "LOSSY_TOKEN" not in capsys.readouterr().err
+
+
+def test_log_before_init_warns_not_raises(monkeypatch, capsys):
+    monkeypatch.setattr(lossy, "run", None)
+    lossy.log({"loss": 1.0})
+    lossy.finish()
+    assert "init" in capsys.readouterr().err

lossy-0.1.0/tests/test_queue.py

@@ -0,0 +1,35 @@
+"""Bounded queue: drop-oldest beyond the cap, exactly one stderr warning."""
+import lossy
+
+
+def test_drop_oldest_beyond_cap_with_single_warning(stub, fast, monkeypatch, capsys):
+    from lossy import client
+    monkeypatch.setattr(client, "QUEUE_MAX", 100)
+    monkeypatch.setattr(client, "FLUSH_INTERVAL", 60.0)
+    monkeypatch.setattr(client, "BATCH_SIZE", 10_000)  # worker never drains early
+    run = lossy.init(project="p", name="dropper", _api=stub.url)
+    for i in range(1, 251):
+        run.log({"loss": i}, step=i)
+    run.finish()
+
+    err = capsys.readouterr().err
+    assert err.count("dropping oldest") == 1, err
+
+    points = [p for r in stub.by_action("log") for p in r["body"]["points"]]
+    steps = [p["step"] for p in points]
+    # oldest 150 dropped; the newest 100 survive in order
+    assert steps == list(range(151, 251))
+
+
+def test_log_never_blocks_when_queue_full(stub, fast, monkeypatch):
+    import time
+    from lossy import client
+    monkeypatch.setattr(client, "QUEUE_MAX", 50)
+    monkeypatch.setattr(client, "FLUSH_INTERVAL", 60.0)
+    monkeypatch.setattr(client, "BATCH_SIZE", 10_000)
+    run = lossy.init(project="p", name="nonblock", _api=stub.url)
+    t0 = time.monotonic()
+    for i in range(5_000):
+        run.log({"loss": i}, step=i)
+    assert time.monotonic() - t0 < 2.0, "log() must never stall training"
+    run.finish()

lossy-0.1.0/tests/test_retry.py

@@ -0,0 +1,45 @@
+"""Retries with exponential backoff; sequence-number idempotency on retry."""
+import lossy
+
+
+def test_retry_after_500_reuses_same_sequence_number(stub, fast):
+    run = lossy.init(project="p", name="retry", _api=stub.url)
+    # let start land cleanly first
+    stub.wait_for(lambda snap: any(
+        r["body"] and r["body"].get("action") == "start" for r in snap))
+    stub.set_failures(2)
+    run.log({"loss": 0.3}, step=1)
+    stub.wait_for(lambda snap: len(
+        [r for r in snap if r["body"] and r["body"].get("action") == "log"]) >= 3,
+        timeout=5.0)
+    run.finish()
+
+    logs = stub.by_action("log")
+    assert len(logs) == 3  # two failed attempts + the success
+    seqs = [r["body"]["seq"] for r in logs]
+    assert seqs[0] == seqs[1] == seqs[2], "retries must resend the same seq"
+    assert logs[0]["body"]["points"] == logs[2]["body"]["points"]
+
+
+def test_backoff_delays_grow_exponentially(stub, fast, monkeypatch):
+    from lossy import client
+    delays = []
+    monkeypatch.setattr(client, "_sleep", delays.append)
+    monkeypatch.setattr(client, "MAX_RETRIES", 3)
+    monkeypatch.setattr(client, "BACKOFF_BASE", 0.25)
+    stub.set_failures(3)  # start exhausts all attempts
+    run = lossy.init(project="p", name="backoff", _api=stub.url)
+    stub.wait_for(lambda snap: len(snap) >= 3, timeout=5.0)
+    run.finish()
+    assert delays[:2] == [0.25, 0.5]
+
+
+def test_distinct_batches_get_increasing_seq(stub, fast):
+    run = lossy.init(project="p", name="seq", _api=stub.url)
+    run.log({"a": 1}, step=1)
+    stub.wait_for(lambda snap: any(
+        r["body"] and r["body"].get("action") == "log" for r in snap))
+    run.log({"a": 2}, step=2)
+    run.finish()
+    seqs = [r["body"]["seq"] for r in stub.by_action("log")]
+    assert len(seqs) == 2 and seqs[0] < seqs[1]

lossy-0.1.0/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "lossy"
+version = "0.1.0"
+source = { editable = "." }