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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: expr_tracker
-Version: 0.2.5
+Version: 0.2.7
 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.7}/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.7}/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.7}/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.7}/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.7}/docs/guide/distributed.md

@@ -73,6 +73,12 @@ together with `group`, which both backends understand:
 | rank 2 | `sft-1-rank2` | `sft-1` |
 | rank 2 of stream `data` | `sft-1-data-rank2` | `sft-1` |
 
+`rank_aware` does not affect this. It decides whether the *local* file is
+sharded; the remote id is decided by `backend_on_rank`. They stay independent on
+purpose — `rank_aware=False` says you serialise the writes to one file yourself,
+and there is no equivalent lock between two processes' wandb clients, so a rank
+that reports still needs an id of its own.
+
 ## Typical setup
 
 ```python

{expr_tracker-0.2.5 → expr_tracker-0.2.7}/docs/guide/spans.md

@@ -158,7 +158,7 @@ await asyncio.gather(work("a"), work("b"))
 
 ## Printing a span as it runs
 
-Pass `print_fn` and the span announces itself, indented one tab per level:
+Pass `print_fn` and the span announces itself, indented two spaces per level:
 
 ```python
 with et.span("step", print_fn=print):
@@ -169,10 +169,10 @@ with et.span("step", print_fn=print):
 
 ```
 -> step  16:41:38
-	-> forward  16:41:38
-		-> attention  16:41:38
-		<- attention  16:41:38  3.074ms
-	<- forward  16:41:38  5.481ms
+  -> forward  16:41:38
+    -> attention  16:41:38
+    <- attention  16:41:38  3.074ms
+  <- forward  16:41:38  5.481ms
 <- step  16:41:38  9.641ms
 ```
 
@@ -188,7 +188,9 @@ and interleave their lines; each is still indented by its own depth, and the
 `->` and `<-` markers pair them up.
 
 Any callable taking one string works — `print`, `logger.info`, a list's `append`
-in tests. It is called on the thread that ran the span, and an exception in it is
+in tests. The indent is spaces rather than a tab so that it survives a log
+prefix: a terminal measures tab stops from the start of the line, so behind
+`... | INFO | ` the first level would collapse to whatever is left of the stop. It is called on the thread that ran the span, and an exception in it is
 logged and swallowed.
 
 Set it for the whole run instead of per span with `span_print_fn`:

{expr_tracker-0.2.5 → expr_tracker-0.2.7}/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.7}/docs/reference/api.md

@@ -177,7 +177,7 @@ span.metrics                                    # what the plugins measured
 `<path>/duration_ms`, `<path>/count` and one key per plugin metric to the open
 row, and appends the full record to `spans.jsonl`.
 
-`print_fn(line)` announces the span's start and end, indented one tab per level.
+`print_fn(line)` announces the span's start and end, indented two spaces per level.
 `plugins` measure a resource across the span; both are inherited by child spans
 and default to the run's `span_print_fn` and `span_plugins`.
 

{expr_tracker-0.2.5 → expr_tracker-0.2.7}/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.7}/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.7/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.7}/src/expr_tracker/spans.py

@@ -26,6 +26,10 @@ _STACK: ContextVar[tuple[Span, ...]] = ContextVar("et_span_stack", default=())
 DURATION_SUFFIX = "duration_ms"
 COUNT_SUFFIX = "count"
 RESERVED_METRICS = frozenset({DURATION_SUFFIX, COUNT_SUFFIX})
+# Spaces, not a tab: a terminal measures tab stops from the start of the line, so
+# behind a log prefix the first level collapses to whatever is left of the stop.
+# Two spaces render the same width wherever the line begins.
+INDENT = "  "
 
 
 _WARNED: set[tuple[str, str, str]] = set()
@@ -180,7 +184,7 @@ class Span:
     def _announce(self, marker: str, duration_ms: float | None):
         if self.print_fn is None:
             return
-        indent = "\t" * self.print_depth
+        indent = INDENT * self.print_depth
         stamp = time.strftime("%H:%M:%S", time.localtime())
         if duration_ms is None:
             line = f"{indent}{marker} {self.name}  {stamp}"

{expr_tracker-0.2.5 → expr_tracker-0.2.7}/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():

{expr_tracker-0.2.5 → expr_tracker-0.2.7}/tests/test_distributed.py

@@ -456,3 +456,25 @@ def test_streams_and_ranks_both_reach_the_backend_name(rank, tmp_path):
     call = backend.inits[0]
     assert call["id"] == "job-data-rank3"
     assert call["group"] == "job" and call["job_type"] == "data"
+
+
+def test_the_backend_id_does_not_follow_rank_aware(rank, tmp_path):
+    """Local sharding and the remote id are separate concerns.
+
+    rank_aware=False promises you serialise writes to one file. Two processes'
+    wandb clients have no such lock, so a reporting rank still needs its own id.
+    """
+    backend = RecordingBackend()
+    rank(2)
+    run = Run(
+        project="dist",
+        name="job",
+        dir=str(tmp_path),
+        backends=[backend],
+        backend_on_rank=None,
+        rank_aware=False,
+    )
+    run.log({"loss": 1.0})
+    run.finish()
+    assert backend.inits[0]["id"] == "job-rank2"
+    assert run.history.log_fp.name == "metrics.jsonl"  # unsharded, as asked

{expr_tracker-0.2.5 → expr_tracker-0.2.7}/tests/test_examples.py

@@ -342,7 +342,7 @@ def test_printing_spans_is_opt_in(profile_step, tmp_path, capsys):
     assert "-> step" not in capsys.readouterr().out
     profile_step.main([*argv(**{"--steps": 2, "--dir": tmp_path}), "--print-spans"])
     printed = capsys.readouterr().out
-    assert "-> step" in printed and "\t-> data" in printed
+    assert "-> step" in printed and "\n  -> data" in printed
 
 
 # ------------------------------------------------------------------ early_stopping