expr-tracker 0.2.5__tar.gz → 0.2.6__tar.gz

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: expr_tracker
-Version: 0.2.5
+Version: 0.2.6
 Summary: Local-first experiment tracking with queryable history and expression-based alerts on your training metrics
 Project-URL: Homepage, https://hspk.github.io/expr_tracker/
 Project-URL: Documentation, https://hspk.github.io/expr_tracker/
@@ -31,13 +31,10 @@ Provides-Extra: all
 Requires-Dist: nvidia-ml-py>=12.0; extra == 'all'
 Requires-Dist: pandas>=1.5; extra == 'all'
 Requires-Dist: polars>=0.20; extra == 'all'
-Requires-Dist: slark>=0.1.28; extra == 'all'
 Requires-Dist: trackio>=0.4.0; extra == 'all'
 Requires-Dist: wandb>=0.21.0; extra == 'all'
 Provides-Extra: gpu
 Requires-Dist: nvidia-ml-py>=12.0; extra == 'gpu'
-Provides-Extra: lark
-Requires-Dist: slark>=0.1.28; extra == 'lark'
 Provides-Extra: pandas
 Requires-Dist: pandas>=1.5; extra == 'pandas'
 Provides-Extra: polars
@@ -92,7 +89,6 @@ et.history(-1, output_type="pd")  # everything, as a DataFrame
 uv add expr_tracker                 # local-first: click, loguru, pydantic only
 uv add "expr_tracker[wandb]"        # mirror to Weights & Biases
 uv add "expr_tracker[trackio]"      # mirror to trackio
-uv add "expr_tracker[lark]"         # Feishu/Lark alert channel
 uv add "expr_tracker[pandas]"       # history(output_type="pandas")
 uv add "expr_tracker[all]"          # everything
 ```
@@ -180,7 +176,7 @@ uv run ruff format src tests
 | `test_distributed.py` | rank shards, `alert_on_rank`, real multi-process runs |
 | `test_wandb.py` | real wandb in offline mode: parameter mapping, step alignment, artifacts |
 | `test_trackio.py` | trackio contract, resume mapping, real end-to-end |
-| `test_lark_live.py` | Lark channel; real delivery when `ET_LARK_TEST_WEBHOOK` is set |
+| `test_lark.py` | Lark card construction; real delivery when `ET_LARK_TEST_WEBHOOK` is set |
 | `test_stress.py` (`slow`) | 100k-row writes, concurrency, cache thrash, write-failure recovery |
 | `test_benchmark.py` (`benchmark`) | throughput, tail latency, query cost, memory stability |
 

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/README.md

@@ -42,7 +42,6 @@ et.history(-1, output_type="pd")  # everything, as a DataFrame
 uv add expr_tracker                 # local-first: click, loguru, pydantic only
 uv add "expr_tracker[wandb]"        # mirror to Weights & Biases
 uv add "expr_tracker[trackio]"      # mirror to trackio
-uv add "expr_tracker[lark]"         # Feishu/Lark alert channel
 uv add "expr_tracker[pandas]"       # history(output_type="pandas")
 uv add "expr_tracker[all]"          # everything
 ```
@@ -130,7 +129,7 @@ uv run ruff format src tests
 | `test_distributed.py` | rank shards, `alert_on_rank`, real multi-process runs |
 | `test_wandb.py` | real wandb in offline mode: parameter mapping, step alignment, artifacts |
 | `test_trackio.py` | trackio contract, resume mapping, real end-to-end |
-| `test_lark_live.py` | Lark channel; real delivery when `ET_LARK_TEST_WEBHOOK` is set |
+| `test_lark.py` | Lark card construction; real delivery when `ET_LARK_TEST_WEBHOOK` is set |
 | `test_stress.py` (`slow`) | 100k-row writes, concurrency, cache thrash, write-failure recovery |
 | `test_benchmark.py` (`benchmark`) | throughput, tail latency, query cost, memory stability |
 

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/docs/design.md

@@ -375,9 +375,12 @@ AlertRule(name, condition, level="warning", title=None,
   timeout.
 - **Only send failures are swallowed**; configuration errors raise at configuration
   time.
-- **Backends**: `lark` (via slark, client reused), `slack`, `dingtalk`, `wecom` and
-  `webhook` (a generic template) use stdlib `urllib`; `email` uses stdlib `smtplib` —
-  **no new hard dependencies**. `register_backend()` extends the set.
+- **Backends**: `lark`, `slack`, `dingtalk`, `wecom` and `webhook` (a generic
+  template) use stdlib `urllib`; `email` uses stdlib `smtplib` — **every channel is
+  dependency-free**. `register_backend()` extends the set. The Lark card layout is
+  built as plain dicts in `backends/cards.py` rather than pulled in with a client
+  library: it is one JSON body, and a whole HTTP stack to shape it was not a trade
+  worth making.
 - **Configuration precedence**: `init(alert=)` > `configure_alert()` >
   `ET_ALERT_CONFIG` file > environment (`ET_LARK_WEBHOOK_URL`, legacy `WEBHOOK_URL`)
   > defaults.

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/docs/getting-started.md

@@ -12,10 +12,13 @@ Only `click`, `loguru` and `pydantic` are required. Everything else is an extra:
 | --- | --- |
 | `wandb` | mirror metrics to Weights & Biases |
 | `trackio` | mirror metrics to trackio |
-| `lark` | Feishu/Lark alert channel |
 | `pandas` / `polars` | `history(output_type=...)` frames |
+| `gpu` | `GpuStats` span plugin, via NVML |
 | `all` | all of the above |
 
+Alert channels need nothing: every one of them, Lark included, is built on the
+standard library.
+
 A missing extra is reported with the exact install command; it never crashes a run.
 
 ## A complete run

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/docs/guide/alerts.md

@@ -90,8 +90,8 @@ et.alert(title="done", text="training finished", level="info", channels=["oncall
 ```
 
 Built-in types: `lark`, `slack`, `dingtalk`, `wecom`, `webhook` (a generic JSON
-template), `email`, `callable`. All but `lark` use only the standard library. Add
-your own with `register_backend()`.
+template), `email`, `callable`. All of them use only the standard library, so no
+channel needs an extra. Add your own with `register_backend()`.
 
 ### Email
 

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/docs/index.md

@@ -36,7 +36,7 @@ or an unserialisable value degrades with a warning; none of them can stop traini
 
 ```bash
 uv add expr_tracker                 # local-first, three small dependencies
-uv add "expr_tracker[all]"          # + wandb, trackio, lark, pandas, polars
+uv add "expr_tracker[all]"          # + wandb, trackio, pandas, polars, gpu
 ```
 
 ## Next

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/pyproject.toml

@@ -40,14 +40,12 @@ dynamic = ["version"]
 
 [project.optional-dependencies]
 # Local-first by default: remote backends and rich frames are opt-in.
-lark = ["slark>=0.1.28"]
 wandb = ["wandb>=0.21.0"]
 trackio = ["trackio>=0.4.0"]
 pandas = ["pandas>=1.5"]
 polars = ["polars>=0.20"]
 gpu = ["nvidia-ml-py>=12.0"]
 all = [
-    "slark>=0.1.28",
     "wandb>=0.21.0",
     "trackio>=0.4.0",
     "pandas>=1.5",
@@ -72,7 +70,6 @@ docs = [
 ]
 dev = [
     "ipykernel>=6.30.1",
-    "slark>=0.1.28",
     "wandb>=0.21.0",
     "trackio>=0.4.0",
     "numpy>=1.24",

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/src/expr_tracker/alerts/backends/__init__.py

@@ -6,7 +6,7 @@ import json
 import smtplib
 from email.message import EmailMessage
 
-from ..models import AlertLevel, AlertMessage, ChannelConfig
+from ..models import AlertLevel, AlertMessage
 from .base import (
     AlertBackend,
     SendError,
@@ -16,6 +16,7 @@ from .base import (
     render_html,
     render_text,
 )
+from .cards import build_card, card_payload
 
 LEVEL_EMOJI = {
     AlertLevel.DEBUG: "🔍",
@@ -56,13 +57,22 @@ class UrlBackend(AlertBackend):
             self.url, payload, self.timeout, self.config.options.get("headers")
         )
 
-    def post_checked(self, payload: dict):
-        """DingTalk and WeCom report failures via errcode inside an HTTP 200 body."""
-        body = self.post(payload)
+    def post_reply(self, payload: dict) -> dict:
+        """Post, and decode the reply these APIs put their verdict in.
+
+        An unreadable body is not a failure: the POST itself succeeded, and some
+        proxies answer 200 with nothing at all.
+        """
+        body = self.post(payload)  # outside the try: a failed POST must raise
         try:
             result = json.loads(body)
         except Exception:
-            return
+            return {}
+        return result if isinstance(result, dict) else {}
+
+    def post_checked(self, payload: dict):
+        """DingTalk and WeCom report failures via errcode inside an HTTP 200 body."""
+        result = self.post_reply(payload)
         code = result.get("errcode")
         if code:
             raise SendError(
@@ -73,45 +83,31 @@ class UrlBackend(AlertBackend):
 
 
 class LarkBackend(UrlBackend):
-    type = "lark"
-
-    def __init__(self, config: ChannelConfig):
-        super().__init__(config)
-        self._client = None
+    """Feishu/Lark bot webhook, as an interactive card."""
 
-    def _lark(self):
-        if self._client is None:
-            from slark import Lark
+    type = "lark"
 
-            options = {k: v for k, v in self.config.options.items() if k != "headers"}
-            self._client = Lark(webhook=self.url, **options)
-        return self._client
+    # Lark answers HTTP 200 and puts the verdict in the body
+    RETRYABLE_CODES = frozenset({9499, 11232, 19024})
 
     def send(self, message: AlertMessage):
         title = f"{LEVEL_EMOJI.get(message.level, '')} {message.title}".strip()
-        text = render_text(message)
-        subtitle = message.subtitle
-        try:
-            client = self._lark()
-        except ImportError as e:  # pragma: no cover - optional extra
+        card = build_card(
+            render_text(message),
+            title,
+            message.subtitle,
+            message.traceback,
+            failed=message.level >= AlertLevel.ERROR,
+        )
+        result = self.post_reply(card_payload(card))
+        # Success is code 0, or StatusCode 0 from the older bot endpoint
+        code = result.get("code") or result.get("StatusCode") or 0
+        if code:
+            detail = result.get("msg") or result.get("StatusMessage")
             raise SendError(
-                f'The lark channel needs slark: pip install "expr_tracker[lark]" ({e})',
-                retryable=False,
-            ) from e
-        try:
-            if message.level >= AlertLevel.ERROR:
-                client.webhook.post_error_card(
-                    msg=text,
-                    traceback=message.traceback or "",
-                    title=title,
-                    subtitle=subtitle,
-                )
-            else:
-                client.webhook.post_success_card(
-                    msg=text, title=title, subtitle=subtitle
-                )
-        except Exception as e:
-            raise SendError(f"Lark webhook failed: {e}") from e
+                f"Lark rejected the message: code={code} msg={detail!r}",
+                retryable=code in self.RETRYABLE_CODES,
+            )
 
 
 class SlackBackend(UrlBackend):

expr_tracker-0.2.6/src/expr_tracker/alerts/backends/cards.py

@@ -0,0 +1,102 @@
+"""Lark (Feishu) interactive message cards.
+
+The card layout is the one ``slark`` builds, reproduced here as plain dicts so
+the Lark channel needs no third-party client: a webhook post is one JSON body
+over stdlib HTTP, which is what every other channel already does.
+
+Reference: https://open.feishu.cn/document/server-docs/im-v1/message-card
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+GREEN = "green"
+RED = "red"
+YES_ICON = "yes_filled"
+ERROR_ICON = "error_filled"
+
+
+def _heading(content: str) -> dict[str, Any]:
+    """A section heading. Lark has no heading element, hence the wrapping."""
+    return {
+        "tag": "column_set",
+        "flex_mode": "none",
+        "horizontal_spacing": "default",
+        "horizontal_align": "left",
+        "background_style": "default",
+        "columns": [
+            {
+                "tag": "column",
+                "background_style": "default",
+                "elements": [
+                    {
+                        "tag": "div",
+                        "text": {
+                            "tag": "plain_text",
+                            "content": content,
+                            "text_size": "heading",
+                            "text_align": "left",
+                            "text_color": "default",
+                        },
+                    }
+                ],
+                "width": "auto",
+                "weight": 1,
+                "vertical_align": "top",
+                "vertical_spacing": "default",
+            }
+        ],
+    }
+
+
+def _code_block(content: str, language: str = "txt") -> dict[str, Any]:
+    return {
+        "tag": "markdown",
+        "content": f"```{language}\n{content}\n```",
+        "text_align": "left",
+        "text_size": "normal",
+    }
+
+
+def _header(title: str, subtitle: str, template: str, icon: str) -> dict[str, Any]:
+    return {
+        "title": {"tag": "plain_text", "content": title},
+        "subtitle": {"tag": "plain_text", "content": subtitle},
+        "template": template,
+        "ud_icon": {"token": icon},
+    }
+
+
+def build_card(
+    message: str,
+    title: str,
+    subtitle: str | None = None,
+    traceback: str | None = None,
+    *,
+    failed: bool = False,
+) -> dict[str, Any]:
+    """One card: a coloured header, the message, and a traceback if there is one."""
+    elements: list[dict[str, Any]] = [
+        _heading("Message"),
+        _code_block(message),
+    ]
+    if traceback and traceback.strip():
+        # Skipped when absent: most alerts are metric conditions, not crashes,
+        # and an empty "Traceback" code block on every one of them is noise
+        elements += [_heading("Traceback"), _code_block(traceback.strip(), "")]
+    return {
+        "header": _header(
+            title,
+            subtitle if subtitle is not None else time.strftime("%Y-%m-%d %H:%M:%S"),
+            RED if failed else GREEN,
+            ERROR_ICON if failed else YES_ICON,
+        ),
+        "elements": elements,
+    }
+
+
+def card_payload(card: dict[str, Any]) -> dict[str, Any]:
+    """The webhook envelope a card has to travel in."""
+    return {"msg_type": "interactive", "card": card}

{expr_tracker-0.2.5 → expr_tracker-0.2.6}/tests/test_alert_backends.py

@@ -75,27 +75,30 @@ def test_custom_headers_are_forwarded(captured):
     assert captured[0]["headers"] == {"X-Token": "t"}
 
 
-def test_lark_uses_error_card_for_errors(monkeypatch):
-    calls: list = []
-
-    class FakeWebhook:
-        def post_success_card(self, **kwargs):
-            calls.append(("success", kwargs))
-
-        def post_error_card(self, **kwargs):
-            calls.append(("error", kwargs))
-
-    class FakeLark:
-        def __init__(self, **kwargs):
-            self.webhook = FakeWebhook()
-
-    backend = build("lark")
-    monkeypatch.setattr(backend, "_lark", lambda: FakeLark())
-    backend.send(message(level="info"))
-    backend.send(message(level="error", traceback="tb"))
-    assert [kind for kind, _ in calls] == ["success", "error"]
-    assert calls[1][1]["traceback"] == "tb"
-    assert calls[0][1]["title"].endswith("Title")  # level emoji prefix
+def test_lark_sends_an_interactive_card(captured):
+    build("lark").send(message(level="info"))
+    payload = captured[0]["payload"]
+    assert payload["msg_type"] == "interactive"
+    assert payload["card"]["header"]["title"]["content"].endswith("Title")
+
+
+@pytest.mark.parametrize(
+    ("level", "template"),
+    [("info", "green"), ("warning", "green"), ("error", "red"), ("critical", "red")],
+)
+def test_the_lark_card_colour_follows_the_level(captured, level, template):
+    build("lark").send(message(level=level))
+    assert captured[0]["payload"]["card"]["header"]["template"] == template
+
+
+def test_a_lark_card_carries_the_traceback(captured):
+    build("lark").send(message(level="error", traceback="tb here"))
+    blocks = [
+        e["content"]
+        for e in captured[0]["payload"]["card"]["elements"]
+        if e["tag"] == "markdown"
+    ]
+    assert any("tb here" in block for block in blocks)
 
 
 def test_callable_backend_requires_handler():