gridrunner 0.6.0__py3-none-any.whl

gridrunner/__init__.py

@@ -0,0 +1,25 @@
+"""GRIDRUNNER producer SDK — fire-and-forget INGEST job events and the
+SIMULATE run stream."""
+
+from .ids import ulid
+from .sdk import (
+    Chunk, Client, Job, Run, connect, emit, init, job, manifest, ping,
+    ping_once, run,
+)
+
+__version__ = "0.6.0"
+__all__ = [
+    "Chunk",
+    "Client",
+    "Job",
+    "Run",
+    "connect",
+    "emit",
+    "init",
+    "job",
+    "manifest",
+    "ping",
+    "ping_once",
+    "run",
+    "ulid",
+]

gridrunner/ids.py

@@ -0,0 +1,29 @@
+"""ULID generation (stdlib-only)."""
+
+import os
+import threading
+import time
+
+_ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_lock = threading.Lock()
+_last: list = [0, 0]  # [ts_ms, randomness as int]
+
+
+def _encode(value: int, length: int) -> str:
+    out = []
+    for _ in range(length):
+        out.append(_ENCODING[value & 0x1F])
+        value >>= 5
+    return "".join(reversed(out))
+
+
+def ulid() -> str:
+    with _lock:
+        ts = int(time.time() * 1000)
+        if ts == _last[0]:
+            _last[1] += 1
+        else:
+            _last[0] = ts
+            _last[1] = int.from_bytes(os.urandom(10), "big")
+        rand = _last[1] & ((1 << 80) - 1)
+    return _encode(ts, 10) + _encode(rand, 16)

gridrunner/sdk.py

@@ -0,0 +1,624 @@
+"""Producer SDK: INGEST job/chunk events plus the SIMULATE run stream,
+fire-and-forget.
+
+Initialized explicitly, like any hosted analytics SDK: pass the core URL
+and its produce token to ``init``; the SDK never reads config files or
+environment variables and never switches targets behind the caller's back.
+
+    import gridrunner as gr
+    gr.init(token="<produce token>", url="https://gridrunner.example.com")
+    gr.init()                                   # local dev core, http://127.0.0.1:7077
+
+    chunks = [{"chunk_id": f"users:{i:03d}", "units": 100_000, "item": "users"}
+              for i in range(20)]
+    with gr.job("etl.appstore.daily", chunks=chunks) as job:
+        for spec in chunks:
+            with job.chunk(spec["chunk_id"]):
+                pull_batch(spec)
+
+Simulation producers stream runs through the same client (INGEST-only
+consumers simply never touch these):
+
+    run = gr.run("mkt.spend_optimizer", levers=levers, seed=7)
+    for t, values in engine.simulate(levers):
+        run.tick(t, values)
+    run.done(metrics={"net_revenue_total": total})
+
+Contractually unable to crash or block the host process: a bounded
+in-memory queue, a background sender thread, drop-with-warning on
+overflow. While the core is unreachable (e.g. a redeploy mid-run) events
+are held in a bounded, liveness-scoped backlog and replayed on reconnect;
+event_id ULIDs make double-delivery harmless. Gridrunner is
+visualization, not persistence: work the core never observed is discarded
+once it finishes instead of being pushed later as stale history.
+"""
+
+from __future__ import annotations
+
+import atexit
+import datetime as _dt
+import json
+import logging
+import math
+import queue
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+
+from .ids import ulid
+
+
+def _default_host() -> str | None:
+    """Short machine name so operators can see where a job runs."""
+    try:
+        return socket.gethostname().split(".")[0] or None
+    except Exception:
+        return None
+
+log = logging.getLogger("gridrunner.sdk")
+
+_DEFAULT_LOCAL_URL = "http://127.0.0.1:7077"
+_URL_REQUIRED_WITH_TOKEN = "gridrunner: url= is required alongside a token"
+
+
+def _resolve_url(url: str | None, token: str | None) -> str | None:
+    if url:
+        return url.rstrip("/")
+    if token:
+        return None
+    return _DEFAULT_LOCAL_URL
+
+_TERMINAL_TYPES = {"job.completed", "job.failed", "run.completed", "run.failed"}
+_PROTECTED_TYPES = {"job.registered", "run.started", "sim.manifest"} | _TERMINAL_TYPES
+_BATCH_LIMIT = 5000
+_BACKLOG_CAP_PER_STREAM = 2000
+_TICK_CAP_PER_RUN = 512
+_WARN_INTERVAL_S = 30.0
+
+
+def _sanitize(obj):
+    if isinstance(obj, float):
+        return obj if math.isfinite(obj) else None
+    if isinstance(obj, dict):
+        return {k: _sanitize(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_sanitize(v) for v in obj]
+    return obj
+
+
+def _dump_line(event: dict) -> str:
+    try:
+        return json.dumps(event, separators=(",", ":"), default=str,
+                          allow_nan=False)
+    except ValueError:
+        return json.dumps(_sanitize(event), separators=(",", ":"),
+                          default=str, allow_nan=False)
+
+
+def _stream_key(event: dict) -> str:
+    entity = event.get("job_id") or event.get("run_id") or event.get("sim_id")
+    if entity:
+        return entity
+    if event.get("service") or event.get("type") == "ping":
+        return f"svc:{event.get('service') or ''}"
+    return ""
+
+
+class _Backlog:
+    """Undelivered events for work that is still worth finishing on the core.
+
+    Liveness-scoped, bounded, in memory. While a job/run is alive its
+    events are retained (compacted) so the visualization can be
+    reconstructed after reconnect. Work the core never observed is dropped
+    entirely the moment it finishes: gridrunner is visualization, not
+    persistence, and a job that lived and died during an outage must not be
+    pushed to the core later as stale history.
+    """
+
+    def __init__(self):
+        self.events: list[dict] = []
+        self.observed: set[str] = set()
+        self.dropped_structural = 0
+
+    def __len__(self) -> int:
+        return len(self.events)
+
+    def add(self, event: dict) -> None:
+        etype = event.get("type", "")
+        if etype == "job.heartbeat":
+            return
+        key = _stream_key(event)
+        if etype in _TERMINAL_TYPES and key and key not in self.observed:
+            self.events = [e for e in self.events if _stream_key(e) != key]
+            return
+        if etype == "ping" and event.get("status") != "error":
+            # ok pings carry no unique information beyond their timestamp;
+            # keep only the newest per series during an outage. Error pings
+            # are all retained — they are the ones worth replaying late.
+            ping_type = event.get("ping_type")
+            self.events = [
+                e for e in self.events
+                if not (e.get("type") == "ping"
+                        and e.get("status") != "error"
+                        and _stream_key(e) == key
+                        and e.get("ping_type") == ping_type)
+            ]
+        if etype == "chunk.progress":
+            chunk_id = event.get("chunk_id")
+            self.events = [
+                e for e in self.events
+                if not (e.get("type") == "chunk.progress"
+                        and _stream_key(e) == key
+                        and e.get("chunk_id") == chunk_id)
+            ]
+        self.events.append(event)
+        if etype == "run.tick":
+            self._thin_ticks(key)
+        if key:
+            self._enforce_cap(key)
+
+    def take(self, limit: int) -> list[dict]:
+        return self.events[:max(limit, 0)]
+
+    def ack(self, batch: list[dict]) -> None:
+        acked = {e.get("event_id") for e in batch}
+        self.events = [e for e in self.events if e.get("event_id") not in acked]
+        for event in batch:
+            key = _stream_key(event)
+            if key:
+                self.observed.add(key)
+
+    def _thin_ticks(self, key: str) -> None:
+        idxs = [i for i, e in enumerate(self.events)
+                if e.get("type") == "run.tick" and _stream_key(e) == key]
+        if len(idxs) <= _TICK_CAP_PER_RUN:
+            return
+        drop = set(idxs[:-1:2])
+        self.events = [e for i, e in enumerate(self.events) if i not in drop]
+
+    def _enforce_cap(self, key: str) -> None:
+        idxs = [i for i, e in enumerate(self.events) if _stream_key(e) == key]
+        excess = len(idxs) - _BACKLOG_CAP_PER_STREAM
+        if excess <= 0:
+            return
+        drop: set[int] = set()
+        for i in idxs:
+            if excess <= 0:
+                break
+            if self.events[i].get("type") not in _PROTECTED_TYPES:
+                drop.add(i)
+                excess -= 1
+        if excess > 0:
+            self.dropped_structural += excess
+        self.events = [e for i, e in enumerate(self.events) if i not in drop]
+
+
+class Client:
+    def __init__(self, url: str, token: str | None = None,
+                 flush_interval_s: float = 0.2, queue_size: int = 20_000,
+                 retry_interval_s: float = 5.0):
+        self.url = url.rstrip("/")
+        self.token = token
+        self.flush_interval_s = flush_interval_s
+        self.retry_interval_s = retry_interval_s
+        self.queue: queue.Queue = queue.Queue(maxsize=queue_size)
+        self._backlog = _Backlog()
+        self._dropped = 0
+        self._last_failure: float | None = None
+        self._last_error: str | None = None
+        self._last_warn = 0.0
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._sender, daemon=True,
+                                        name="gridrunner-sdk")
+        self._thread.start()
+        atexit.register(self.close)
+
+    def emit(self, event: dict) -> None:
+        event = {"event_id": ulid(), "ts": time.time() * 1000, **event}
+        try:
+            self.queue.put_nowait(event)
+        except queue.Full:
+            self._dropped += 1
+            if self._dropped in (1, 100, 10_000):
+                log.warning("gridrunner queue full; dropped %d events", self._dropped)
+
+    def ping(self, ping_type: str = "default", status: str = "ok",
+             description: str | None = None,
+             expected_next_ts: "float | _dt.datetime | None" = None) -> None:
+        """Fire-and-forget status report for this producer's recurring work.
+
+        The ping carries no service name: the core resolves it from the
+        produce token at ingestion — the name the producer was registered
+        with when its token was minted — so producers can never contaminate
+        each other's series. ``ping_type`` is an understandable name of the
+        recurring process itself (e.g. ``daily-export``, ``queue-sweep``).
+
+        Regular pings (``status="ok"``) teach the core the cadence; a missed
+        beat surfaces on the PINGS tab. ``status="error"`` reports "alive,
+        but something went wrong" and should carry a description.
+
+        ``expected_next_ts`` (epoch ms or a ``datetime``) declares when the
+        next ping is due. Declare it when the cadence is too sparse to
+        learn quickly (weekly, monthly): GRIDRUNNER alarms on that deadline
+        instead of waiting to learn the pattern.
+        """
+        self.emit(_ping_event(ping_type, status, description,
+                              expected_next_ts))
+
+    def close(self, timeout: float = 3.0) -> None:
+        if self._stop.is_set():
+            return
+        self._stop.set()
+        self._thread.join(timeout=timeout)
+
+    def _sender(self) -> None:
+        while True:
+            stopping = self._stop.wait(self.flush_interval_s)
+            fresh: list[dict] = []
+            while len(fresh) < _BATCH_LIMIT:
+                try:
+                    fresh.append(self.queue.get_nowait())
+                except queue.Empty:
+                    break
+            now = time.monotonic()
+            throttled = (self._last_failure is not None
+                         and now - self._last_failure < self.retry_interval_s
+                         and not stopping)
+            if throttled:
+                for event in fresh:
+                    self._backlog.add(event)
+            else:
+                batch = self._backlog.take(_BATCH_LIMIT - len(fresh)) + fresh
+                if batch:
+                    if self._post(batch):
+                        self._last_failure = None
+                        self._backlog.ack(batch)
+                        self._drain_backlog()
+                    else:
+                        self._last_failure = now
+                        for event in fresh:
+                            self._backlog.add(event)
+                        self._warn_unreachable()
+            if stopping and self.queue.empty():
+                return
+
+    def _drain_backlog(self) -> None:
+        while len(self._backlog):
+            batch = self._backlog.take(_BATCH_LIMIT)
+            if not self._post(batch):
+                self._last_failure = time.monotonic()
+                return
+            self._backlog.ack(batch)
+
+    def _post(self, batch: list[dict]) -> bool:
+        body = "\n".join(_dump_line(e) for e in batch).encode()
+        req = urllib.request.Request(
+            self.url + "/v1/events", data=body, method="POST",
+            headers={"Content-Type": "application/x-ndjson"},
+        )
+        if self.token:
+            req.add_header("Authorization", f"Bearer {self.token}")
+        try:
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                ok = 200 <= resp.status < 300
+                if ok:
+                    self._last_error = None
+                return ok
+        except urllib.error.HTTPError as exc:
+            self._last_error = f"HTTP {exc.code}"
+            return False
+        except Exception as exc:
+            self._last_error = exc.__class__.__name__
+            return False
+
+    def _warn_unreachable(self) -> None:
+        now = time.monotonic()
+        if now - self._last_warn < _WARN_INTERVAL_S:
+            return
+        self._last_warn = now
+        if self._last_error == "HTTP 401":
+            log.warning(
+                "gridrunner core at %s rejected the produce token (401);"
+                " holding %d events for live jobs", self.url, len(self._backlog))
+        else:
+            log.warning(
+                "gridrunner core at %s unreachable (%s);"
+                " holding %d events for live jobs",
+                self.url, self._last_error or "error", len(self._backlog))
+
+
+_client: Client | None = None
+
+
+def init(token: str | None = None, url: str | None = None, **kwargs) -> Client:
+    """Configure the module-level client with explicit credentials.
+
+    ``init(token=..., url=...)`` targets a deployed core; ``init()`` with
+    neither targets the unauthenticated local dev core at
+    ``http://127.0.0.1:7077``. A token without ``url=`` is a
+    ``ValueError``. The SDK reads no config files and no environment
+    variables; the target and token stay exactly as the caller set them
+    for the life of the process.
+    """
+    global _client
+    resolved = _resolve_url(url, token)
+    if resolved is None:
+        raise ValueError(_URL_REQUIRED_WITH_TOKEN)
+    if _client is not None:
+        _client.close()
+    _client = Client(resolved, token=token, **kwargs)
+    return _client
+
+
+def connect(url: str | None = None, token: str | None = None, **kwargs) -> Client:
+    """Deprecated alias of :func:`init` (older url-first signature)."""
+    return init(token=token, url=url, **kwargs)
+
+
+def emit(event: dict) -> None:
+    if _client is not None:
+        _client.emit(event)
+
+
+def _ping_event(ping_type: str, status: str, description: str | None,
+                expected_next_ts: "float | _dt.datetime | None") -> dict:
+    event: dict = {"type": "ping", "ping_type": ping_type, "status": status}
+    if description:
+        event["description"] = description
+    if expected_next_ts is not None:
+        if isinstance(expected_next_ts, _dt.datetime):
+            expected_next_ts = expected_next_ts.timestamp() * 1000
+        event["expected_next_ts"] = float(expected_next_ts)
+    return event
+
+
+def ping(ping_type: str = "default", status: str = "ok",
+         description: str | None = None,
+         expected_next_ts: "float | _dt.datetime | None" = None) -> None:
+    """Fire-and-forget status report, unrelated to job heartbeats.
+
+    The service name is resolved server-side from the produce token —
+    the caller only names the recurring process (``ping_type``). See
+    :meth:`Client.ping`.
+    """
+    if _client is not None:
+        _client.ping(ping_type, status=status, description=description,
+                     expected_next_ts=expected_next_ts)
+
+
+def ping_once(ping_type: str = "default", *, token: str | None = None,
+              status: str = "ok", description: str | None = None,
+              expected_next_ts: "float | _dt.datetime | None" = None,
+              url: str | None = None, wait: bool = False,
+              timeout_s: float = 5.0) -> bool | None:
+    """One-shot stateless ping: token and ping in the same call, one direct
+    HTTP POST to ``/v1/events`` — no ``init``, no persistent client, no
+    queue, no backlog. Built for cron scripts and one-liners.
+
+    Fire-and-forget by default: returns ``None`` immediately and delivers
+    on a short-lived non-daemon thread, so a script that exits right after
+    pinging doesn't lose the ping — the process lingers at most
+    ``timeout_s``. ``wait=True`` performs the POST inline and returns
+    ``True``/``False``. Never raises either way: a monitoring call must
+    not break the cron it monitors.
+
+    ``url`` resolves like :func:`init`: required alongside a token, the
+    local dev core without one. A token without ``url`` is logged and
+    dropped rather than raised — the call still never breaks its cron. The
+    service name still comes from the token server-side; the one-shot call
+    changes delivery, not identity.
+    """
+    resolved = _resolve_url(url, token)
+    if resolved is None:
+        log.warning("gridrunner ping_once dropped: %s", _URL_REQUIRED_WITH_TOKEN)
+        return False if wait else None
+    event = {"event_id": ulid(), "ts": time.time() * 1000,
+             **_ping_event(ping_type, status, description, expected_next_ts)}
+
+    def deliver() -> bool:
+        req = urllib.request.Request(
+            resolved + "/v1/events", data=_dump_line(event).encode(),
+            method="POST",
+            headers={"Content-Type": "application/x-ndjson"},
+        )
+        if token:
+            req.add_header("Authorization", f"Bearer {token}")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+                return 200 <= resp.status < 300
+        except Exception as exc:
+            log.warning("gridrunner ping_once to %s failed (%s)",
+                        resolved, exc.__class__.__name__)
+            return False
+
+    if wait:
+        return deliver()
+    threading.Thread(target=deliver, daemon=False,
+                     name="gridrunner-ping-once").start()
+    return None
+
+
+class Chunk:
+    def __init__(self, job: "Job", chunk_id: str, units: float, worker: str | None,
+                 item: str | None = None):
+        self.job = job
+        self.chunk_id = chunk_id
+        self.units = units
+        self.worker = worker
+        self.item = item
+        self._start = 0.0
+
+    def progress(self, fraction: float) -> None:
+        emit({"type": "chunk.progress", "job_id": self.job.job_id,
+              "chunk_id": self.chunk_id, "fraction": max(0.0, min(1.0, fraction))})
+
+    def __enter__(self) -> "Chunk":
+        self._start = time.monotonic()
+        event = {"type": "chunk.started", "job_id": self.job.job_id,
+                 "chunk_id": self.chunk_id}
+        if self.worker:
+            event["worker"] = self.worker
+        if self.item:
+            event["item"] = self.item
+        emit(event)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        duration_ms = int((time.monotonic() - self._start) * 1000)
+        if exc_type is None:
+            emit({"type": "chunk.completed", "job_id": self.job.job_id,
+                  "chunk_id": self.chunk_id, "duration_ms": duration_ms,
+                  "units": self.units})
+        else:
+            emit({"type": "chunk.failed", "job_id": self.job.job_id,
+                  "chunk_id": self.chunk_id, "error": f"{exc_type.__name__}: {exc}"})
+            self.job.had_failures = True
+        return False
+
+
+class Job:
+    def __init__(self, job_type_id: str, chunks=None, label: str | None = None,
+                 total_units: float | None = None, meta: dict | None = None,
+                 job_id: str | None = None, heartbeat_s: float | None = None,
+                 expected_silence_s: float | None = None,
+                 host: str | None = None):
+        self.job_id = job_id or f"j_{ulid().lower()}"
+        self.job_type_id = job_type_id
+        self.label = label or job_type_id
+        self.meta = meta or {}
+        self.heartbeat_s = heartbeat_s
+        self.expected_silence_s = expected_silence_s
+        self.host = host or _default_host()
+        self._hb_stop: threading.Event | None = None
+        self._hb_thread: threading.Thread | None = None
+        self.had_failures = False
+        self.chunk_specs: list[dict] = []
+        self._units_by_id: dict[str, float] = {}
+        if isinstance(chunks, dict):
+            chunks = [{"chunk_id": k, "units": v, "label": k} for k, v in chunks.items()]
+        for i, c in enumerate(chunks or []):
+            if isinstance(c, str):
+                c = {"chunk_id": c, "units": 1, "label": c}
+            c.setdefault("chunk_id", f"c{i:03d}")
+            c.setdefault("units", 1)
+            c.setdefault("label", c["chunk_id"])
+            c.setdefault("item", c["chunk_id"])
+            self.chunk_specs.append(c)
+            self._units_by_id[c["chunk_id"]] = float(c["units"])
+        self.total_units = total_units or sum(self._units_by_id.values()) or 1.0
+
+    def chunk(self, chunk_id: str, units: float | None = None,
+              worker: str | None = None, item: str | None = None) -> Chunk:
+        if chunk_id not in self._units_by_id:
+            spec = {"chunk_id": chunk_id, "units": units or 1,
+                    "label": chunk_id, "item": item or chunk_id}
+            self.chunk_specs.append(spec)
+            self._units_by_id[chunk_id] = float(spec["units"])
+        return Chunk(self, chunk_id, units or self._units_by_id[chunk_id],
+                     worker, item)
+
+    def register(self) -> "Job":
+        event = {"type": "job.registered", "job_id": self.job_id,
+                 "job_type_id": self.job_type_id, "label": self.label,
+                 "total_units": self.total_units,
+                 "chunks": [dict(c) for c in self.chunk_specs],
+                 "meta": self.meta}
+        if self.heartbeat_s:
+            event["heartbeat_s"] = float(self.heartbeat_s)
+        if self.expected_silence_s:
+            event["expected_silence_s"] = float(self.expected_silence_s)
+        if self.host:
+            event["host"] = self.host
+        emit(event)
+        self._start_heartbeat()
+        return self
+
+    def _start_heartbeat(self) -> None:
+        if not self.heartbeat_s or self._hb_thread is not None:
+            return
+        stop = threading.Event()
+
+        def beat() -> None:
+            while not stop.wait(self.heartbeat_s):
+                emit({"type": "job.heartbeat", "job_id": self.job_id})
+
+        self._hb_stop = stop
+        self._hb_thread = threading.Thread(
+            target=beat, daemon=True, name=f"gridrunner-hb-{self.job_id}")
+        self._hb_thread.start()
+
+    def _stop_heartbeat(self) -> None:
+        if self._hb_stop is not None:
+            self._hb_stop.set()
+        if self._hb_thread is not None:
+            self._hb_thread.join(timeout=0.2)
+        self._hb_stop = None
+        self._hb_thread = None
+
+    def complete(self) -> None:
+        self._stop_heartbeat()
+        emit({"type": "job.completed", "job_id": self.job_id})
+
+    def fail(self, error: str = "") -> None:
+        self._stop_heartbeat()
+        emit({"type": "job.failed", "job_id": self.job_id, "error": error})
+
+    def __enter__(self) -> "Job":
+        return self.register()
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        if exc_type is None:
+            self.complete()
+        else:
+            self.fail(f"{exc_type.__name__}: {exc}")
+        return False
+
+
+def job(job_type_id: str, chunks=None, **kwargs) -> Job:
+    return Job(job_type_id, chunks=chunks, **kwargs)
+
+
+# ── SIMULATE surface: run streams and sim manifests ─────────────────────
+
+
+class Run:
+    def __init__(self, sim_id: str, levers: dict | None = None, seed: int | None = None,
+                 found_by: str = "operator", run_id: str | None = None):
+        self.run_id = run_id or f"r_{ulid().lower()}"
+        self.sim_id = sim_id
+        emit({"type": "run.started", "run_id": self.run_id, "sim_id": sim_id,
+              "levers": levers or {}, "seed": seed, "found_by": found_by})
+
+    def tick(self, t: int, values: dict) -> None:
+        emit({"type": "run.tick", "run_id": self.run_id, "t": t, "values": values})
+
+    def done(self, metrics: dict | None = None, feasible: bool = True,
+             objective: float | None = None, violated: list | None = None) -> None:
+        event = {"type": "run.completed", "run_id": self.run_id,
+                 "metrics": metrics or {}, "feasible": feasible}
+        if objective is not None:
+            event["objective"] = objective
+        if violated:
+            event["violated"] = violated
+        emit(event)
+
+    def fail(self, error: str = "") -> None:
+        emit({"type": "run.failed", "run_id": self.run_id, "error": error})
+
+    def best(self, objective: float) -> None:
+        emit({"type": "search.best", "run_id": self.run_id,
+              "sim_id": self.sim_id, "objective": objective})
+
+
+def run(sim_id: str, levers: dict | None = None, **kwargs) -> Run:
+    return Run(sim_id, levers=levers, **kwargs)
+
+
+def manifest(manifest_dict: dict, version: int | None = None) -> None:
+    event = {"type": "sim.manifest", "sim_id": manifest_dict.get("sim_id"),
+             "manifest": manifest_dict}
+    if version is not None:
+        event["version"] = version
+    emit(event)

gridrunner-0.6.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: gridrunner
+Version: 0.6.0
+Summary: Producer SDK for GRIDRUNNER — fire-and-forget job progress events
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# GRIDRUNNER Python SDK
+
+Standard-library-only producer client for reporting bounded jobs and
+service status pings — super-light health monitoring for services and
+recurring tasks — to GRIDRUNNER. See the [repository README](../README.md)
+for the job/item/chunk/unit model, the ping mechanic, authentication,
+delivery guarantees, and installation.
+
+## Configure
+
+Initialize once near process startup with explicit credentials — the SDK
+reads no environment variables and no config files:
+
+```python
+import gridrunner as gr
+
+client = gr.init(token=read_secret("gridrunner_produce_token"),
+                 url="https://gridrunner.example.com")
+```
+
+A token without `url=` raises `ValueError`. With neither, `init()` targets
+the local unauthenticated dev core:
+
+```python
+client = gr.init()                             # http://127.0.0.1:7077
+```
+
+The token is also your identity: the name your producer was registered
+with when the token was minted becomes the service name of every ping you
+send.
+
+All options:
+
+```python
+client = gr.init(
+    token=token,
+    url="https://gridrunner.example.com",
+    flush_interval_s=0.2,
+    queue_size=20_000,
+    retry_interval_s=5.0,
+)
+```
+
+## Preferred usage
+
+Declare chunks up front and use context managers. Successful exits emit
+completion; exceptions emit failure and are re-raised.
+
+```python
+import gridrunner as gr
+
+gr.init(token=read_secret("gridrunner_produce_token"),
+        url="https://gridrunner.example.com")
+
+chunks = [
+    {
+        "chunk_id": f"orders:{month}",
+        "item": "orders",
+        "label": month,
+        "units": estimated_rows,
+    }
+    for month, estimated_rows in monthly_estimates.items()
+]
+
+with gr.job(
+    "etl.orders.monthly.v1",
+    chunks=chunks,
+    label="Export orders",
+    meta={"service": "billing-export"},
+    heartbeat_s=30,
+) as job:
+    for spec in chunks:
+        with job.chunk(spec["chunk_id"], worker=worker_name):
+            export_month(spec["label"])
+```
+
+## Manual lifecycle
+
+Use manual methods when a context manager does not match the host framework:
+
+```python
+job = gr.job(
+    "model.forecast.v3",
+    chunks=[
+        {"chunk_id": "load", "item": "prepare", "units": 1},
+        {"chunk_id": "fit", "item": "model", "units": 10},
+        {"chunk_id": "write", "item": "output", "units": 1},
+    ],
+    expected_silence_s=300,
+).register()
+
+try:
+    with job.chunk("fit"):
+        fit_model()
+    job.complete()
+except Exception as exc:
+    job.fail(f"{type(exc).__name__}: {exc}")
+    raise
+```
+
+For one genuinely indivisible chunk, report a measured fraction:
+
+```python
+with job.chunk("fit") as chunk:
+    for completed, total in train():
+        chunk.progress(completed / total)
+```
+
+## Service pings
+
+For services and independent regular jobs — cron cycles, daemons,
+schedulers — use the ping mechanic instead of jobs: one call per cycle,
+and GRIDRUNNER learns the cadence and alarms on silence or errors by
+itself.
+
+The ping only names the recurring process (`ping_type` — an
+understandable name like `daily-export` or `queue-sweep`). The service
+name is resolved server-side from the produce token — the name the
+producer was registered with — so producers can never contaminate each
+other's series.
+
+```python
+def daily_cycle():
+    try:
+        run_export()
+        gr.ping("daily-export")
+    except Exception as exc:
+        gr.ping("daily-export", status="error",
+                description=f"{type(exc).__name__}: {exc}")
+        raise
+```
+
+If the cadence is too sparse to learn quickly (weekly, monthly), declare
+when the next ping is due — GRIDRUNNER alarms on that deadline instead of
+waiting to learn the pattern:
+
+```python
+gr.ping("monthly-report", expected_next_ts=next_run_at)  # epoch ms or datetime
+```
+
+For cron scripts that shouldn't carry a client lifecycle at all, use the
+one-shot call — token and ping in one line, no `init`, no queue:
+
+```python
+gr.ping_once("daily-export", token=tok, url=core_url)
+```
+
+See [Service pings](../README.md#service-pings) in the repository README
+for the full contract.
+
+## Chunk plan formats
+
+Full dictionaries preserve item grouping and weights:
+
+```python
+chunks = [
+    {"chunk_id": "users:0", "item": "users", "label": "0–49k", "units": 50_000},
+    {"chunk_id": "users:1", "item": "users", "label": "50k–99k", "units": 50_000},
+]
+```
+
+Convenience forms are accepted:
+
+```python
+chunks = {"users:0": 50_000, "users:1": 50_000}
+chunks = ["load", "fit", "write"]  # each gets one unit
+```
+
+## API
+
+### `init(token=None, url=None, **client_options)`
+
+Configures the module-level client used by `emit()`, `job()`, and
+`ping()`. A token requires an explicit `url` (`ValueError` otherwise);
+with neither it targets a local core at `http://127.0.0.1:7077`. The
+target never changes behind the caller's back. `connect(url=None,
+token=None, ...)` remains as a deprecated alias.
+
+### `job(job_type_id, chunks=None, **options) -> Job`
+
+Options:
+
+| Option | Meaning |
+|---|---|
+| `label` | Human-readable run label |
+| `total_units` | Override sum of chunk units |
+| `meta` | JSON metadata attached to registration |
+| `job_id` | Stable caller-provided run ID; otherwise generated ULID |
+| `heartbeat_s` | Automatic heartbeat interval |
+| `expected_silence_s` | Expected quiet-work bound |
+
+### `Job`
+
+- `register()` — emits `job.registered` and starts heartbeat.
+- `chunk(id, units=None, worker=None, item=None)` — returns a chunk context.
+- `complete()` — stops heartbeat and emits `job.completed`.
+- `fail(error="")` — stops heartbeat and emits `job.failed`.
+
+### `Chunk`
+
+- Context entry emits `chunk.started`.
+- `progress(fraction)` emits a clamped measured fraction in `[0, 1]`.
+- Normal context exit emits `chunk.completed` with duration.
+- Exceptional context exit emits `chunk.failed` and re-raises.
+
+### `ping(ping_type="default", status="ok", description=None, expected_next_ts=None)`
+
+Reports a recurring status ping — a mechanic separate from jobs (see the
+[repository README](../README.md#service-pings)). The service name is
+resolved server-side from the produce token; `ping_type` names the
+recurring process:
+
+```python
+gr.ping("daily-export")
+gr.ping("daily-export", status="error", description="table locked")
+gr.ping("monthly-report", expected_next_ts=next_run_at)
+```
+
+`expected_next_ts` (epoch ms or a `datetime`) optionally declares when the
+next ping is due, for cadences too sparse to learn quickly.
+
+### `ping_once(ping_type="default", *, token=None, status="ok", description=None, expected_next_ts=None, url=None, wait=False, timeout_s=5.0)`
+
+One-shot stateless ping for cron scripts and one-liners: token and ping in
+the same call, one direct HTTP POST — no `init`, no persistent client, no
+queue, no backlog (outage-safe replay is what you give up).
+
+Fire-and-forget by default: returns `None` immediately and delivers on a
+short-lived non-daemon thread, so a script that exits right after pinging
+doesn't lose the ping (the process lingers at most `timeout_s`).
+`wait=True` performs the POST inline and returns `True`/`False`. Never
+raises either way. `url` resolves like `init`: required alongside a token
+(a token without `url` is logged and dropped), the local dev core without
+one.
+
+```python
+gr.ping_once("daily-export", token=tok, url=core_url)                  # returns immediately
+ok = gr.ping_once("daily-export", token=tok, url=core_url, wait=True)  # opt-in: block → bool
+gr.ping_once("daily-export", token=tok, url=core_url, status="error",
+             description="table locked")
+```
+
+### `emit(event)`
+
+Queues a raw event on the configured module client. Prefer the structured
+job/chunk API unless integrating an unsupported lifecycle.
+
+### `Client`
+
+An independent client for applications that cannot use module-level state:
+
+```python
+client = gr.Client(url, token=token)
+client.emit({"type": "job.heartbeat", "job_id": job_id})
+client.close()
+```
+
+Call `close()` during graceful shutdown to flush the in-memory queue.
+
+## Failure behavior
+
+- Connection and HTTP errors never propagate into host work.
+- Undelivered events are held in a bounded, liveness-scoped in-memory
+  backlog: live jobs keep compacted events (latest progress per chunk, no
+  heartbeats; ok pings compact to the newest per series, error pings are
+  all kept) and replay on reconnect; jobs that start and finish entirely
+  while the core is unreachable are discarded, never sent late.
+- Events are assigned idempotency IDs before queueing.
+- Non-finite floats are converted to JSON `null`.
+- A full queue drops new events and logs at increasing thresholds; held
+  backlogs log a rate-limited warning (distinct message on 401).

gridrunner-0.6.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+gridrunner/__init__.py,sha256=ViIXTA43x2AsmHx9qlebRvcw90qV4c1K0AfLqz-5jU8,436
+gridrunner/ids.py,sha256=dwnwYb1BCVZCv1VCvX-Dmi1RWemLLzLIgmFL3pG8MjY,704
+gridrunner/sdk.py,sha256=d013Wfr1k7W5ULWJgoNGCK9aN0ixSO4291iqYduMGd0,24519
+gridrunner-0.6.0.dist-info/licenses/LICENSE,sha256=VywLwAcDu7Rk1s3he7PX6zq_f95A-8IIhhbzsvYeP4w,1075
+gridrunner-0.6.0.dist-info/METADATA,sha256=Y5LJeNwmfasfVq71fPsQvbkAQnLH-XjZSo6qHyxKIfk,9051
+gridrunner-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gridrunner-0.6.0.dist-info/top_level.txt,sha256=09IqiGvxPvqbbvRTvphrimHEz4PQcYJ0Wd-lAlY7E4o,11
+gridrunner-0.6.0.dist-info/RECORD,,

gridrunner-0.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gridrunner-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GRIDRUNNER authors
+
+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.

gridrunner-0.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gridrunner