notiboard 0.1.0__tar.gz

notiboard-0.1.0/LICENSE

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

notiboard-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: notiboard
+Version: 0.1.0
+Summary: Monitor AI training on your phone with a drop-in SummaryWriter replacement.
+Author-email: Noti <noti@tech-webs.com>
+License-Expression: MIT
+Project-URL: Homepage, https://noti.tech-webs.com
+Project-URL: Repository, https://github.com/noti-app/noti-sdk
+Project-URL: Documentation, https://noti.tech-webs.com/document
+Keywords: tensorboard,machine-learning,training,monitoring,notifications,mlops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: Pillow<12,>=10
+Requires-Dist: tensorboardX<3,>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# notiboard
+
+`notiboard` is both the PyPI distribution name and the Python import package.
+
+Monitor your AI training on your phone with a drop-in replacement for TensorBoard's `SummaryWriter`.
+
+## Installation
+
+```bash
+pip install notiboard
+```
+
+## Quick Start
+
+```python
+from notiboard import NotiWriter
+
+writer = NotiWriter(
+    log_dir="runs/experiment1",
+    noti_api_key="nk_your_key_here",   # from the Noti app: Settings > API Keys
+    noti_project="my-project",
+    noti_run_name="experiment-001",    # optional, auto-generated if not set
+)
+
+for step in range(1000):
+    loss = train_step()
+    writer.add_scalar("loss/train", loss, step)
+    writer.set_progress(step, 1000, f"Step {step}/1000")
+
+writer.send_notification("Training complete", "Final loss: 0.001", "Done.")
+writer.close()
+```
+
+All standard TensorBoard `SummaryWriter` methods are preserved. If PyTorch is installed,
+`NotiWriter` uses `torch.utils.tensorboard`. Otherwise it falls back to `tensorboardX`,
+which is included as a package dependency.
+
+## Configuration
+
+| Argument | Env Variable | Default | Description |
+|---|---|---|---|
+| `noti_api_key` | `NOTI_API_KEY` | — | API key from the Noti app (required) |
+| `noti_server` | `NOTI_SERVER` | `https://notiapi.tech-webs.com` | Noti server URL |
+| `noti_project` | — | `"default"` | Project name |
+| `noti_run_name` | — | Auto-generated | Run name |
+| `noti_enabled` | `NOTI_ENABLED` | `1` | Set `0` to disable Noti sync |
+| `noti_complete_on_close` | — | `True` | Mark the run as completed when `close()` is called |
+
+## Release Files
+
+This package is configured for standard PyPI release tooling:
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+There are helper scripts under `sdk/scripts/` and a release checklist in `sdk/RELEASING.md`.
+
+## License
+
+MIT

notiboard-0.1.0/README.md

@@ -0,0 +1,63 @@
+# notiboard
+
+`notiboard` is both the PyPI distribution name and the Python import package.
+
+Monitor your AI training on your phone with a drop-in replacement for TensorBoard's `SummaryWriter`.
+
+## Installation
+
+```bash
+pip install notiboard
+```
+
+## Quick Start
+
+```python
+from notiboard import NotiWriter
+
+writer = NotiWriter(
+    log_dir="runs/experiment1",
+    noti_api_key="nk_your_key_here",   # from the Noti app: Settings > API Keys
+    noti_project="my-project",
+    noti_run_name="experiment-001",    # optional, auto-generated if not set
+)
+
+for step in range(1000):
+    loss = train_step()
+    writer.add_scalar("loss/train", loss, step)
+    writer.set_progress(step, 1000, f"Step {step}/1000")
+
+writer.send_notification("Training complete", "Final loss: 0.001", "Done.")
+writer.close()
+```
+
+All standard TensorBoard `SummaryWriter` methods are preserved. If PyTorch is installed,
+`NotiWriter` uses `torch.utils.tensorboard`. Otherwise it falls back to `tensorboardX`,
+which is included as a package dependency.
+
+## Configuration
+
+| Argument | Env Variable | Default | Description |
+|---|---|---|---|
+| `noti_api_key` | `NOTI_API_KEY` | — | API key from the Noti app (required) |
+| `noti_server` | `NOTI_SERVER` | `https://notiapi.tech-webs.com` | Noti server URL |
+| `noti_project` | — | `"default"` | Project name |
+| `noti_run_name` | — | Auto-generated | Run name |
+| `noti_enabled` | `NOTI_ENABLED` | `1` | Set `0` to disable Noti sync |
+| `noti_complete_on_close` | — | `True` | Mark the run as completed when `close()` is called |
+
+## Release Files
+
+This package is configured for standard PyPI release tooling:
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+There are helper scripts under `sdk/scripts/` and a release checklist in `sdk/RELEASING.md`.
+
+## License
+
+MIT

notiboard-0.1.0/notiboard/__init__.py

@@ -0,0 +1,33 @@
+"""
+notiboard - Monitor AI training on your phone.
+
+Drop-in replacement for TensorBoard's SummaryWriter with Noti server sync.
+
+Quick start:
+    from notiboard import NotiWriter
+
+    writer = NotiWriter(
+        log_dir="runs/experiment1",
+        noti_api_key="nk_your_key_here",       # from the Noti app
+        noti_project="my-project",
+        noti_run_name="experiment-001",         # optional
+    )
+
+    for step in range(1000):
+        loss = train_step()
+        writer.add_scalar("loss/train", loss, step)
+        writer.set_progress(step, 1000, f"Step {step}/1000")
+
+    writer.send_notification(
+        title="Training Complete",
+        preview="Loss: 0.001",
+        content="Training finished after 1000 steps. Final loss: 0.001",
+    )
+    writer.close()
+"""
+
+from notiboard.config import NotiConfig
+from notiboard.writer import NotiWriter
+
+__all__ = ["NotiWriter", "NotiConfig"]
+__version__ = "0.1.0"

notiboard-0.1.0/notiboard/client.py

@@ -0,0 +1,332 @@
+"""
+HTTP client for communicating with the Noti server.
+
+Runs a background daemon thread with an internal queue.
+All public enqueue_* methods are thread-safe and non-blocking from the caller.
+
+Reliability guarantees:
+- Failed batches are retried with exponential backoff (up to max_retries).
+- If a batch ultimately fails, it is dropped and a warning is logged.
+  (Persistent disk-based queue is out of scope for v0.1.)
+- close() / flush_and_close() waits up to close_timeout for in-flight uploads.
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+import time
+from typing import Any
+
+import httpx
+
+from notiboard.config import NotiConfig
+
+logger = logging.getLogger("noti")
+
+# Sentinel to tell the background thread to exit after draining the queue.
+_STOP = object()
+
+
+class NotiClient:
+    """
+    Manages HTTP communication with the Noti server.
+
+    Architecture:
+      caller → enqueue_* → _queue → background thread → _flush() → HTTP POST
+    """
+
+    def __init__(self, config: NotiConfig, run_id: str) -> None:
+        self._config = config
+        self._run_id = run_id
+
+        # Items are dicts with a 'type' key; _STOP is used as a stop sentinel.
+        self._queue: queue.Queue[Any] = queue.Queue()
+
+        self._http = httpx.Client(
+            base_url=config.server_url,
+            headers={"X-Noti-Key": config.api_key or ""},
+            timeout=config.request_timeout,
+        )
+        self._thread = threading.Thread(
+            target=self._flush_loop, daemon=True, name="noti-uploader"
+        )
+        self._thread.start()
+
+    # ─── Public API ──────────────────────────────────────────────────────────
+
+    def enqueue_scalar(
+        self, tag: str, step: int, value: float, wall_time: float | None = None
+    ) -> None:
+        self._queue.put_nowait(
+            {"type": "scalar", "tag": tag, "step": step, "value": value, "wall_time": wall_time}
+        )
+        self._maybe_flush()
+
+    def enqueue_histogram(
+        self, tag: str, step: int, histogram_data: dict[str, Any]
+    ) -> None:
+        self._queue.put_nowait(
+            {"type": "histogram", "tag": tag, "step": step, **histogram_data}
+        )
+        self._maybe_flush()
+
+    def enqueue_text(
+        self, tag: str, step: int, content: str, wall_time: float | None = None
+    ) -> None:
+        self._queue.put_nowait(
+            {"type": "text", "tag": tag, "step": step, "content": content, "wall_time": wall_time}
+        )
+        self._maybe_flush()
+
+    def send_progress(
+        self, current_step: int, total_steps: int, message: str | None = None
+    ) -> None:
+        """Synchronously update the training progress bar in the Noti app."""
+        try:
+            resp = self._http.put(
+                f"/api/v1/progress/{self._run_id}",
+                json={
+                    "current_step": current_step,
+                    "total_steps": total_steps,
+                    "message": message,
+                },
+            )
+            resp.raise_for_status()
+        except Exception as exc:
+            logger.warning("Noti: failed to send progress update: %s", exc)
+
+    def send_notification(
+        self,
+        title: str,
+        preview: str,
+        content: str,
+        notification_type: str = "info",
+    ) -> None:
+        """Synchronously send a push notification and store it in the inbox."""
+        try:
+            resp = self._http.post(
+                "/api/v1/notifications",
+                json={
+                    "title": title,
+                    "preview": preview,
+                    "content": content,
+                    "run_id": self._run_id,
+                    "notification_type": notification_type,
+                },
+            )
+            resp.raise_for_status()
+        except Exception as exc:
+            logger.warning("Noti: failed to send notification: %s", exc)
+
+    def send_error(self, title: str, preview: str | None = None, content: str | None = None) -> None:
+        """Send an error/exception notification (red ❌ indicator in the inbox)."""
+        self.send_notification(
+            title=title,
+            preview=preview or title,
+            content=content or title,
+            notification_type="error",
+        )
+
+    def send_alert(self, title: str, preview: str | None = None, content: str | None = None) -> None:
+        """Send a milestone/alert notification (yellow ⚡ indicator in the inbox)."""
+        self.send_notification(
+            title=title,
+            preview=preview or title,
+            content=content or title,
+            notification_type="alert",
+        )
+
+    def upload_image(
+        self,
+        tag: str,
+        step: int,
+        image_bytes: bytes,
+        *,
+        width: int,
+        height: int,
+        fmt: str = "PNG",
+        wall_time: float | None = None,
+    ) -> None:
+        """
+        Upload a single image to the Noti server (synchronous, fires immediately).
+
+        Args:
+            tag: Metric tag name.
+            step: Training step.
+            image_bytes: Raw image bytes (PNG or JPEG).
+            width: Image width in pixels.
+            height: Image height in pixels.
+            fmt: Image format string, e.g. "PNG" or "JPEG".
+            wall_time: Optional epoch timestamp.
+        """
+        ext = fmt.lower()
+        content_type = f"image/{'jpeg' if ext in ('jpg', 'jpeg') else ext}"
+        try:
+            resp = self._http.post(
+                "/api/v1/metrics/images/upload",
+                data={
+                    "run_id": self._run_id,
+                    "tag": tag,
+                    "step": step,
+                    "wall_time": wall_time,
+                    "width": width,
+                    "height": height,
+                    "format": fmt.upper(),
+                },
+                files={"file": (f"{step}.{ext}", image_bytes, content_type)},
+            )
+            if resp.status_code == 401:
+                logger.warning("Noti: image upload rejected (401). Check API key.")
+                return
+            resp.raise_for_status()
+        except Exception as exc:
+            logger.warning("Noti: failed to upload image '%s' step %d: %s", tag, step, exc)
+
+    def mark_run_status(self, status: str) -> None:
+        """
+        Update the run status on the server.
+
+        Args:
+            status: One of 'running', 'completed', 'failed', 'stopped'.
+        """
+        try:
+            resp = self._http.patch(
+                f"/api/v1/runs/{self._run_id}/status",
+                json={"status": status},
+            )
+            resp.raise_for_status()
+            logger.info("Noti: run %s marked as %s", self._run_id, status)
+        except Exception as exc:
+            logger.warning("Noti: failed to mark run status '%s': %s", status, exc)
+
+    def flush_and_close(self, complete_on_close: bool = True) -> None:
+        """
+        Flush all pending metrics, optionally mark the run as completed, then close.
+
+        Blocks up to config.close_timeout seconds for in-flight uploads to finish.
+        """
+        # Enqueue sentinel so the background thread exits after draining
+        self._queue.put(_STOP)
+        self._thread.join(timeout=self._config.close_timeout)
+        if self._thread.is_alive():
+            logger.warning(
+                "Noti: background upload thread did not finish within %ss. "
+                "Some metrics may have been dropped.",
+                self._config.close_timeout,
+            )
+
+        if complete_on_close:
+            self.mark_run_status("completed")
+
+        self._http.close()
+
+    # ─── Internal ────────────────────────────────────────────────────────────
+
+    def _maybe_flush(self) -> None:
+        """Trigger an immediate flush if the queue has reached batch_size."""
+        if self._queue.qsize() >= self._config.batch_size:
+            # Signal flush by waking the thread (it drains on each wake)
+            self._flush_now()
+
+    def _flush_loop(self) -> None:
+        """Background thread: flush every flush_interval seconds, or on stop."""
+        while True:
+            try:
+                # Wait up to flush_interval for something to appear in the queue
+                item = self._queue.get(timeout=self._config.flush_interval)
+            except queue.Empty:
+                # Periodic flush
+                self._flush_batch_from_queue()
+                continue
+
+            if item is _STOP:
+                # Drain remaining items then exit
+                self._flush_batch_from_queue()
+                break
+
+            # Put the item back (we peeked) and flush everything
+            self._queue.put(item)
+            self._flush_batch_from_queue()
+
+    def _flush_batch_from_queue(self) -> None:
+        """Drain all items currently in the queue and POST them as one batch."""
+        scalars: list[dict[str, Any]] = []
+        histograms: list[dict[str, Any]] = []
+        texts: list[dict[str, Any]] = []
+
+        while True:
+            try:
+                item = self._queue.get_nowait()
+            except queue.Empty:
+                break
+            if item is _STOP:
+                # Re-enqueue the stop sentinel so the caller's join() still works
+                self._queue.put(_STOP)
+                break
+            item_type = item.pop("type", None)
+            if item_type == "scalar":
+                scalars.append(item)
+            elif item_type == "histogram":
+                histograms.append(item)
+            elif item_type == "text":
+                texts.append(item)
+
+        if not scalars and not histograms and not texts:
+            return
+
+        payload = {
+            "run_id": self._run_id,
+            "scalars": scalars,
+            "histograms": histograms,
+            "texts": texts,
+        }
+        self._post_with_retry("/api/v1/metrics/batch", payload, scalars + histograms + texts)
+
+    def _post_with_retry(
+        self, path: str, payload: dict[str, Any], original_items: list[dict[str, Any]]
+    ) -> None:
+        """POST with exponential backoff. Re-enqueues items if all retries fail."""
+        for attempt in range(self._config.max_retries):
+            try:
+                resp = self._http.post(path, json=payload)
+                if resp.status_code == 401:
+                    logger.warning(
+                        "Noti: authentication failed (401). Check your API key. Metrics dropped."
+                    )
+                    return
+                resp.raise_for_status()
+                return
+            except httpx.HTTPStatusError as exc:
+                if exc.response.status_code < 500:
+                    # 4xx (other than 401) → don't retry
+                    logger.warning(
+                        "Noti: server rejected batch (HTTP %d). Metrics dropped.",
+                        exc.response.status_code,
+                    )
+                    return
+                wait = min(2**attempt, 30)
+                logger.debug(
+                    "Noti: upload attempt %d/%d failed (HTTP %d), retrying in %ds",
+                    attempt + 1, self._config.max_retries, exc.response.status_code, wait,
+                )
+            except Exception as exc:
+                wait = min(2**attempt, 30)
+                logger.debug(
+                    "Noti: upload attempt %d/%d failed (%s), retrying in %ds",
+                    attempt + 1, self._config.max_retries, exc, wait,
+                )
+            if attempt < self._config.max_retries - 1:
+                time.sleep(wait)
+
+        total = len(original_items)
+        logger.warning(
+            "Noti: failed to upload %d item(s) after %d attempts. Data dropped.",
+            total,
+            self._config.max_retries,
+        )
+
+    # Compatibility alias for callers that call _flush_now directly
+    def _flush_now(self) -> None:
+        pass  # Flush is handled lazily by the background thread on next cycle

notiboard-0.1.0/notiboard/config.py

@@ -0,0 +1,65 @@
+"""Configuration management for the Noti SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+#: Default server URL — can be overridden by NOTI_SERVER env var or constructor arg.
+DEFAULT_SERVER_URL = "https://notiapi.tech-webs.com"
+
+
+@dataclass
+class NotiConfig:
+    """
+    Holds all configuration for a NotiWriter instance.
+
+    Priority: constructor argument > environment variable > built-in default.
+    """
+
+    #: Noti server base URL. Defaults to NOTI_SERVER env var or the official server.
+    server_url: str = field(
+        default_factory=lambda: os.getenv("NOTI_SERVER", DEFAULT_SERVER_URL)
+    )
+
+    #: Your Noti API key (starts with 'nk_'). Shown once when created in the app.
+    api_key: str | None = field(default_factory=lambda: os.getenv("NOTI_API_KEY"))
+
+    #: Project name. Creates the project if it doesn't exist.
+    project: str = "default"
+
+    #: Run name. Auto-generated timestamp-based name if not provided.
+    run_name: str | None = None
+
+    #: Set False to disable Noti sync (TensorBoard still works normally).
+    enabled: bool = field(
+        default_factory=lambda: os.getenv("NOTI_ENABLED", "1") != "0"
+    )
+
+    #: Automatically mark the run as 'completed' when writer.close() is called.
+    complete_on_close: bool = True
+
+    #: Number of metrics to buffer before triggering an immediate upload.
+    batch_size: int = 100
+
+    #: Seconds between automatic batch uploads.
+    flush_interval: float = 5.0
+
+    #: Maximum attempts for each failed upload before the batch is dropped.
+    max_retries: int = 5
+
+    #: Timeout (seconds) for HTTP requests to the Noti server.
+    request_timeout: float = 10.0
+
+    #: Maximum seconds to wait for in-flight uploads when close() is called.
+    close_timeout: float = 30.0
+
+    def validate(self) -> None:
+        """Raise ValueError if required fields are missing when Noti is enabled."""
+        if not self.enabled:
+            return
+        if not self.api_key:
+            raise ValueError(
+                "Noti API key is required. Pass noti_api_key= or set the NOTI_API_KEY "
+                "environment variable. Create an API key in the Noti app under Settings > API Keys."
+            )