expr-tracker 0.3.0__tar.gz → 0.3.2__tar.gz

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: expr_tracker
-Version: 0.3.0
+Version: 0.3.2
 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/
@@ -27,6 +27,7 @@ Requires-Python: >=3.10
 Requires-Dist: click>=8.1.0
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
 Provides-Extra: all
 Requires-Dist: nvidia-ml-py>=12.0; extra == 'all'
 Requires-Dist: pandas>=1.5; extra == 'all'

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/docs/design.md

@@ -118,6 +118,11 @@ so timing a region adds no row. The tree, with timestamps and attributes, goes t
 `spans[.stream][.rankN].jsonl` through a second `JsonlWriter`, enqueued rather
 than appended so a span does not pay for a flush decision of its own.
 
+The committed history row is also the fan-out boundary. Summary, alerts and
+remote backends consume the exact row emitted by `HistoryStore`, rather than the
+individual `log()` calls that assembled it. Span and plugin metrics therefore
+reach every sink without a second metric path.
+
 Plugins hang off the same two hooks. `start` runs before the clock starts and
 `end` after it stops, so a plugin never inflates the duration it reports on; what
 `end` returns is merged into the span's metrics under the span's own path, which

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/docs/guide/backends.md

@@ -16,15 +16,17 @@ optional.
 
 | Call | Forwarded as |
 | --- | --- |
-| `et.log(data, step, commit)` | `backend.log(data, step=<resolved>, commit=<resolved>)` |
+| committed history row | `backend.log(metrics, step=<resolved>, commit=True)` |
 | `et.init(...)` | `backend.init(project, name, config, entity, tags, notes, resume, ...)` |
 | `et.define_metric(name, **kw)` | `backend.define_metric` if it has one |
 | `et.log_artifact(...)` | `backend.log_artifact` if it has one |
 | `et.finish(exit_code)` | `backend.finish()` |
 
-The **resolved** step matters: two `log()` calls for one step stay one step on the
-backend too, and a step dropped by the local step policy is never forwarded. A
-backend that does not accept `commit` (trackio) simply does not receive it.
+Local history assembles the row first. Summary, alerts and remote backends then
+receive that same committed row, including span and plugin metrics. Two `log()`
+calls for one step therefore produce one backend call, and a step dropped by the
+local step policy is never forwarded. A backend that does not accept `commit`
+(trackio) simply does not receive it.
 
 ## Failure handling
 

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/docs/guide/cli.md

@@ -89,3 +89,17 @@ et alert "node 3 is on fire" --level critical --channel oncall
 
 Channels come from the same configuration the library uses: `ET_ALERT_CONFIG` or the
 `ET_LARK_WEBHOOK_URL` environment variable. See [Alerts](alerts.md).
+
+`et alert` automatically loads `.env` from the directory where you invoke it,
+before resolving alert configuration. Existing environment variables take
+precedence, including empty values. It does not search parent directories; a
+missing `.env` is fine. Use `--no-dotenv` to disable loading.
+
+```dotenv
+# .env
+ET_LARK_WEBHOOK_URL=https://example.com/your-webhook
+```
+
+Quoted values, comments, and `${VAR}` expansion are supported; shell commands are
+not executed. Keep secrets out of version control. This loading applies only to
+`et alert`, not other CLI commands or the Python API.

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/pyproject.toml

@@ -34,6 +34,7 @@ dependencies = [
     "click>=8.1.0",
     "loguru>=0.7.3",
     "pydantic>=2.0",
+    "python-dotenv>=1.0",
 ]
 
 dynamic = ["version"]

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/src/expr_tracker/cli.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 
 import json
 import time
+from pathlib import Path
 
 import click
+from dotenv import load_dotenv
 
 from .alerts import alert as send_alert
 from .alerts.dispatch import Dispatcher
@@ -26,8 +28,21 @@ def main():
 @click.option("--title", default="Alert", help="Title of the alert")
 @click.option("--level", default="info", help="info | warning | error | critical")
 @click.option("--channel", "channels", multiple=True, help="Restrict to these channels")
-def alert(msg: str, title: str, level: str, channels: tuple[str, ...]):
-    """Send a manual alert."""
+@click.option(
+    "--no-dotenv", is_flag=True, help="Skip loading .env from the current directory"
+)
+def alert(
+    msg: str, title: str, level: str, channels: tuple[str, ...], no_dotenv: bool
+):
+    """Send a manual alert, loading the current directory's .env by default."""
+    if not no_dotenv:
+        try:
+            with Path(".env").open(encoding="utf-8") as stream:
+                load_dotenv(stream=stream, override=False)
+        except FileNotFoundError:
+            pass
+        except (OSError, UnicodeError) as exc:
+            raise click.ClickException(f"Could not read .env: {exc}") from exc
     send_alert(title=title, text=msg, level=level, channels=list(channels) or None)
 
 

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/src/expr_tracker/run.py

@@ -15,7 +15,7 @@ from typing import Any, Literal
 from loguru import logger
 
 from .artifacts import Artifact, ArtifactStore, coerce_artifact
-from .history import HistoryStore, current_rank, resolve_commit
+from .history import HistoryStore, current_rank
 from .history.naming import resolve_artifact_root, sidecar_filename
 from .summary import Summary
 
@@ -245,34 +245,32 @@ class Run:
     # ------------------------------------------------------------------ logging
 
     def _on_commit(self, record: dict):
-        if self.alerts is not None:
-            self.alerts.on_step(record)
-
-    def log(self, data: dict, step: int | None = None, commit: bool | None = None):
-        """Log metrics, mirroring ``wandb.log(data, step=..., commit=...)``.
-
-        All sinks share one timeline: if local history rejects the call (closed run,
-        or a backward step), the summary and remote backends are skipped too.
-        """
-        resolved_step = self.history.log(data, step=step, commit=commit)
-        if resolved_step is None:
-            return
+        metrics = {
+            key: value
+            for key, value in record.items()
+            if isinstance(key, str) and not key.startswith("_")
+        }
+        step = record["_step"]
         try:
-            self.summary.observe(data)
+            self.summary.observe(metrics)
         except Exception as e:  # a sink must never break the training loop
             logger.warning(f"Failed to update summary: {e}")
         for name, backend in self.backends.items():
-            # Forward the resolved step and commit so a backend's row layout
-            # matches the local history instead of drifting on its own counter.
-            extra = (
-                {"commit": resolve_commit(step, commit)}
-                if self._takes_commit.get(name)
-                else {}
-            )
+            extra = {"commit": True} if self._takes_commit.get(name) else {}
             try:
-                backend.log(data, step=resolved_step, **extra)
+                backend.log(metrics, step=step, **extra)
             except Exception as e:
                 logger.warning(f"Failed to log metrics to {name}: {e}")
+        if self.alerts is not None:
+            self.alerts.on_step(record)
+
+    def log(self, data: dict, step: int | None = None, commit: bool | None = None):
+        """Log metrics, mirroring ``wandb.log(data, step=..., commit=...)``.
+
+        Local history owns row assembly. Summary, alerts and remote backends receive
+        the same complete row only after it commits, including span/plugin metrics.
+        """
+        self.history.log(data, step=step, commit=commit)
 
     def history_query(self, *args, **kwargs):
         return self.history.get(*args, **kwargs)

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/tests/test_artifacts.py

@@ -252,7 +252,7 @@ def test_backend_receives_commit_argument(tmp_path):
         et.log({"v": 1}, step=3, commit=False)
     finally:
         et.finish()
-    assert calls == [({"v": 1}, 3, False)]
+    assert calls == [({"v": 1}, 3, True)]
 
 
 def test_legacy_backend_without_commit_still_works(tmp_path):
@@ -313,7 +313,7 @@ def test_rejected_step_reaches_no_sink(tmp_path):
 
     et.init(project="p", name="mono", dir=str(tmp_path), backends=[Backend()])
     try:
-        et.log({"loss": 1.0}, step=10)
+        et.log({"loss": 1.0}, step=10, commit=True)
         et.log({"loss": 99.0}, step=5)  # rejected under the default step policy
         assert forwarded == [{"loss": 1.0}]
         assert dict(et.summary()) == {"loss": 1.0}

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/tests/test_cli.py

@@ -1,6 +1,7 @@
 """The full CLI surface: every command, every format, and their error paths."""
 
 import json
+import os
 
 import pytest
 from click.testing import CliRunner
@@ -10,7 +11,9 @@ from expr_tracker.history import HistoryStore
 
 
 @pytest.fixture
-def runner():
+def runner(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(os, "environ", os.environ.copy())
     return CliRunner()
 
 
@@ -237,6 +240,81 @@ def test_alert_without_a_message_fails(runner, channel):
     assert runner.invoke(cli.main, ["alert"]).exit_code != 0
 
 
+def test_alert_loads_dotenv_before_resolving_channels(runner, monkeypatch, tmp_path):
+    from expr_tracker.alerts import load_config
+
+    monkeypatch.delenv("ET_LARK_WEBHOOK_URL", raising=False)
+    monkeypatch.delenv("ET_ALERT_CONFIG", raising=False)
+    (tmp_path / ".env").write_text(
+        '# Alert settings\nexport ET_LARK_WEBHOOK_URL="https://example.test/hook"\n',
+        encoding="utf-8",
+    )
+    configs = []
+    monkeypatch.setattr(cli, "send_alert", lambda **kwargs: configs.append(load_config()))
+
+    invoke(runner, "alert", "hello")
+
+    assert any(
+        c.type == "lark" and c.resolve_url() == "https://example.test/hook"
+        for c in configs[0].channels
+    )
+
+
+@pytest.mark.parametrize("existing", ["from-shell", ""])
+def test_alert_dotenv_preserves_existing_environment(
+    runner, channel, monkeypatch, tmp_path, existing
+):
+    monkeypatch.setenv("ET_TEST_DOTENV", existing)
+    (tmp_path / ".env").write_text("ET_TEST_DOTENV=from-file\n", encoding="utf-8")
+
+    invoke(runner, "alert", "hello")
+
+    assert os.environ["ET_TEST_DOTENV"] == existing
+    assert len(channel) == 1
+
+
+def test_alert_does_not_search_parent_dotenv(runner, channel, monkeypatch, tmp_path):
+    monkeypatch.delenv("ET_TEST_DOTENV", raising=False)
+    (tmp_path / ".env").write_text("ET_TEST_DOTENV=parent\n", encoding="utf-8")
+    child = tmp_path / "child"
+    child.mkdir()
+    monkeypatch.chdir(child)
+
+    invoke(runner, "alert", "hello")
+
+    assert "ET_TEST_DOTENV" not in os.environ
+    assert len(channel) == 1
+
+
+def test_alert_can_skip_dotenv(runner, channel, monkeypatch, tmp_path):
+    monkeypatch.delenv("ET_TEST_DOTENV", raising=False)
+    (tmp_path / ".env").write_text("ET_TEST_DOTENV=from-file\n", encoding="utf-8")
+
+    invoke(runner, "alert", "hello", "--no-dotenv")
+
+    assert "ET_TEST_DOTENV" not in os.environ
+    assert len(channel) == 1
+
+
+def test_alert_reports_unreadable_dotenv(runner, channel, tmp_path):
+    (tmp_path / ".env").mkdir()
+
+    result = runner.invoke(cli.main, ["alert", "hello"])
+
+    assert result.exit_code != 0
+    assert "Could not read .env" in result.output
+    assert not channel
+
+
+def test_other_commands_do_not_load_dotenv(runner, monkeypatch, tmp_path):
+    monkeypatch.delenv("ET_TEST_DOTENV", raising=False)
+    (tmp_path / ".env").write_text("ET_TEST_DOTENV=from-file\n", encoding="utf-8")
+
+    invoke(runner, "rules", "explain", "loss > 1")
+
+    assert "ET_TEST_DOTENV" not in os.environ
+
+
 # ------------------------------------------------------------------ rules
 
 

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/tests/test_hot_paths.py

@@ -236,7 +236,7 @@ def test_the_summary_survives_finish(run, tmp_path):
 
 def test_a_dropped_step_does_not_touch_the_summary(run):
     run()
-    et.log({"loss": 1.0}, step=5)
+    et.log({"loss": 1.0}, step=5, commit=True)
     et.log({"loss": 99.0}, step=1)
     assert dict(et.summary())["loss"] == 1.0
 

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/tests/test_review_regressions.py

@@ -473,11 +473,11 @@ def test_alias_added_on_a_dedup_reuse_is_persisted(tmp_path):
         et.finish()
 
 
-def test_summary_ignores_non_string_keys(tmp_path):
+def test_summary_matches_history_key_encoding(tmp_path):
     et.init(project="p", name="s", dir=str(tmp_path), backends=[])
     try:
         et.log({(1, 2): 3, b"k": 4, "loss": 5})
-        assert dict(et.summary()) == {"loss": 5}
+        assert dict(et.summary()) == {"(1, 2)": 3, "k": 4, "loss": 5}
     finally:
         et.finish()
 

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/tests/test_run_backends.py

@@ -137,7 +137,7 @@ def test_backend_receives_init_log_and_finish(tmp_path):
         tags=["a"],
         notes="hello",
     )
-    run.log({"loss": 1.0}, step=0)
+    run.log({"loss": 1.0}, step=0, commit=True)
     run.define_metric("loss", summary="min")
     run.finish()
 
@@ -146,8 +146,7 @@ def test_backend_receives_init_log_and_finish(tmp_path):
     assert init_kwargs["project"] == "p" and init_kwargs["config"] == {"lr": 0.1}
     assert init_kwargs["tags"] == ["a"] and init_kwargs["notes"] == "hello"
     assert backend.calls[1][1] == ({"loss": 1.0},)
-    # an explicit step defers the commit locally, so the backend defers it too
-    assert backend.calls[1][2] == {"step": 0, "commit": False}
+    assert backend.calls[1][2] == {"step": 0, "commit": True}
 
 
 def test_backend_is_named_after_its_class(tmp_path):
@@ -286,7 +285,7 @@ def test_rejected_step_reaches_no_sink(tmp_path):
     backend = FakeBackend()
     run = Run(project="p", name="r", dir=str(tmp_path), backends=[backend])
     try:
-        run.log({"loss": 1.0}, step=5)
+        run.log({"loss": 1.0}, step=5, commit=True)
         run.log({"loss": 2.0}, step=1)  # backwards: dropped
         assert [c[1][0] for c in run.backends["fakebackend"].calls[1:]] == [
             {"loss": 1.0}
@@ -296,6 +295,27 @@ def test_rejected_step_reaches_no_sink(tmp_path):
         run.finish()
 
 
+def test_committed_row_fans_out_span_metrics(tmp_path):
+    backend = FakeBackend()
+    et.init(project="p", name="r", dir=str(tmp_path), backends=[backend])
+    try:
+        et.log({"loss": 1.0}, commit=False)
+        with et.span("forward"):
+            pass
+        et.log({"accuracy": 0.5})
+
+        log_call = backend.calls[1]
+        metrics = log_call[1][0]
+        assert metrics["loss"] == 1.0
+        assert metrics["accuracy"] == 0.5
+        assert metrics["count/forward"] == 1
+        assert "time_ms/forward" in metrics
+        assert et.summary()["count/forward"] == 1
+        assert "time_ms/forward" in et.summary()
+    finally:
+        et.finish()
+
+
 def test_finish_is_idempotent(tmp_path):
     backend = FakeBackend()
     run = Run(project="p", name="r", dir=str(tmp_path), backends=[backend])

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/tests/test_trackio.py

@@ -140,9 +140,11 @@ def test_trackio_receives_the_resolved_step(tmp_path, fake_trackio):
         run.log({"loss": 1.0})
         run.log({"acc": 0.5}, step=0, commit=False)
         run.log({"acc2": 0.6}, step=0)
+        run.history.flush(commit_open=True)
         logs = [call for name, call in fake_trackio.calls if name == "log"]
-        assert [entry["step"] for entry in logs] == [0, 0, 0]
+        assert [entry["step"] for entry in logs] == [0, 0]
         assert logs[0]["metrics"] == {"loss": 1.0}
+        assert logs[1]["metrics"] == {"acc": 0.5, "acc2": 0.6}
     finally:
         run.finish()
 
@@ -150,7 +152,7 @@ def test_trackio_receives_the_resolved_step(tmp_path, fake_trackio):
 def test_a_dropped_step_never_reaches_trackio(tmp_path, fake_trackio):
     run = Run(project="p", name="r", dir=str(tmp_path), backends=["trackio"])
     try:
-        run.log({"loss": 1.0}, step=5)
+        run.log({"loss": 1.0}, step=5, commit=True)
         run.log({"loss": 2.0}, step=1)  # backwards: dropped locally
         logs = [call for name, call in fake_trackio.calls if name == "log"]
         assert [entry["step"] for entry in logs] == [5]

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/tests/test_wandb.py

@@ -142,9 +142,9 @@ def test_several_logs_for_one_step_stay_one_wandb_step(run):
 def test_an_explicit_step_defers_the_commit_on_wandb_too(run):
     instance = run(name="explicit")
     instance.log({"a": 1}, step=7)
-    assert wandb.run.step == 7  # positioned, not yet advanced
+    assert wandb.run.step == 0
     instance.log({"b": 2}, step=7)
-    assert wandb.run.step == 7
+    assert wandb.run.step == 0
     instance.log({"c": 3}, step=8, commit=True)
     assert wandb.run.step == 9
 

{expr_tracker-0.3.0 → expr_tracker-0.3.2}/uv.lock

@@ -463,6 +463,7 @@ dependencies = [
     { name = "click" },
     { name = "loguru" },
     { name = "pydantic" },
+    { name = "python-dotenv" },
 ]
 
 [package.optional-dependencies]
@@ -517,6 +518,7 @@ requires-dist = [
     { name = "polars", marker = "extra == 'all'", specifier = ">=0.20" },
     { name = "polars", marker = "extra == 'polars'", specifier = ">=0.20" },
     { name = "pydantic", specifier = ">=2.0" },
+    { name = "python-dotenv", specifier = ">=1.0" },
     { name = "trackio", marker = "extra == 'all'", specifier = ">=0.4.0" },
     { name = "trackio", marker = "extra == 'trackio'", specifier = ">=0.4.0" },
     { name = "wandb", marker = "extra == 'all'", specifier = ">=0.21.0" },