expr-tracker 0.2.0__tar.gz → 0.2.2__tar.gz

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/.gitignore

@@ -14,3 +14,8 @@ test.ipynb
 .coverage
 htmlcov/
 site/
+
+# Tracker run output: the default dir, and whatever people point --dir at
+tracker/
+outputs/
+runs/

expr_tracker-0.2.2/LICENSE

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

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/PKG-INFO

@@ -1,8 +1,28 @@
 Metadata-Version: 2.4
 Name: expr_tracker
-Version: 0.2.0
-Summary: Add your description here
+Version: 0.2.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/
+Project-URL: Repository, https://github.com/HSPK/expr_tracker
+Project-URL: Issues, https://github.com/HSPK/expr_tracker/issues
+Project-URL: Changelog, https://github.com/HSPK/expr_tracker/releases
 Author-email: HSPK <whxway@whu.edu.cn>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alerting,deep-learning,experiment-tracking,machine-learning,mlops,monitoring,training,wandb
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1.0
 Requires-Dist: loguru>=0.7.3
@@ -27,6 +47,11 @@ Description-Content-Type: text/markdown
 
 # Experiment Tracker
 
+[![PyPI](https://img.shields.io/pypi/v/expr-tracker)](https://pypi.org/project/expr-tracker/)
+[![Python](https://img.shields.io/pypi/pyversions/expr-tracker)](https://pypi.org/project/expr-tracker/)
+[![License](https://img.shields.io/pypi/l/expr-tracker)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-github.io-blue)](https://hspk.github.io/expr_tracker/)
+
 A local-first experiment tracker. Metrics land in a JSONL file you own, stay
 queryable while the run is live, and can trigger alerts from an expression language.
 `wandb` and `trackio` are optional mirrors, not requirements.
@@ -141,3 +166,7 @@ Published to GitHub Pages by `.github/workflows/docs.yaml` on every push to `mai
 Internals: [`docs/design.md`](docs/design.md) (data model and key invariants) and
 [`docs/architecture.md`](docs/architecture.md) (module map, read/write paths,
 concurrency model).
+
+## License
+
+[MIT](LICENSE)

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/README.md

@@ -1,5 +1,10 @@
 # Experiment Tracker
 
+[![PyPI](https://img.shields.io/pypi/v/expr-tracker)](https://pypi.org/project/expr-tracker/)
+[![Python](https://img.shields.io/pypi/pyversions/expr-tracker)](https://pypi.org/project/expr-tracker/)
+[![License](https://img.shields.io/pypi/l/expr-tracker)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-github.io-blue)](https://hspk.github.io/expr_tracker/)
+
 A local-first experiment tracker. Metrics land in a JSONL file you own, stay
 queryable while the run is live, and can trigger alerts from an expression language.
 `wandb` and `trackio` are optional mirrors, not requirements.
@@ -114,3 +119,7 @@ Published to GitHub Pages by `.github/workflows/docs.yaml` on every push to `mai
 Internals: [`docs/design.md`](docs/design.md) (data model and key invariants) and
 [`docs/architecture.md`](docs/architecture.md) (module map, read/write paths,
 concurrency model).
+
+## License
+
+[MIT](LICENSE)

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/docs/design.md

@@ -199,15 +199,23 @@ unary   := ("-"|"+") unary | postfix
 postfix := primary ("[" window "]")?
 primary := NUMBER | DURATION | ident | ident "(" args ")" | "(" expr ")"
 window  := INT (points) | DURATION (30s / 5m / 2h)
-ident   := [A-Za-z_][A-Za-z0-9_.]* | `anything`
+ident   := [A-Za-z_][A-Za-z0-9_.@]* ("/" [A-Za-z0-9_.@]+)*   # train/loss, val/m1/acc@16
+         | "quoted" | 'quoted' | `quoted`                    # anything else
 ```
 
+A `/` joins an identifier only when a name character follows it immediately, so
+division has to be spaced: `a/b` is one metric, `a / b` divides. That makes the
+common case (`train/loss`) free of ceremony at the cost of `loss/2` naming a metric
+rather than halving `loss`. Quoted forms produce names, never string literals — the
+grammar has no strings, and the function table is a closed whitelist.
+
 A hand-written lexer and Pratt parser, **not Python's `ast`**: Python reads
 `diff(m1)>50 | m1>5` as `diff(m1) > (50|m1) > 5`. Precedence, low to high:
 `or < and < not < comparison < +- < */% < unary < call/window`.
 
 **Metric resolution**: exact name → `.` replaced by `/` → error with close-match
-suggestions. So `eval.acc` finds `eval/acc`; use backticks for exotic names.
+suggestions. So `eval.acc` finds `eval/acc`; quote anything the bare grammar cannot
+express.
 
 ### C.2 Three-valued logic (Kleene)
 

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/docs/guide/alerts.md

@@ -29,8 +29,9 @@ Key points, covered fully in [Alert expressions](../reference/expressions.md):
   `loss[5m]` the last 5 minutes.
 - Precedence is `or < and < not < comparison < arithmetic` — **not** Python's. So
   `diff(m1) > 50 | m1 > 5` parses the way it reads, as `(diff(m1) > 50) or (m1 > 5)`.
-- `.` in a metric name resolves to `/`, so `eval.acc` finds `eval/acc`. Use backticks
-  for anything exotic: `` `a-b c` ``.
+- Metric names may contain `/` and `@` directly (`train/loss`, `val/m1/acc@16`), so
+  division has to be spaced: `a/b` is one metric, `a / b` divides. Quote anything
+  else with `"`, `'` or backticks: `"train loss"`.
 - Missing data, too few points, NaN and division by zero all evaluate to UNKNOWN,
   which never fires and never changes state. Warm-up cannot produce false alarms.
 
@@ -92,6 +93,69 @@ 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()`.
 
+### Email
+
+Email needs an SMTP server to send *from*, even when the recipient is Gmail.
+
+```python
+et.init(
+    project="demo",
+    alert={
+        "channels": [
+            {
+                "type": "email",
+                "name": "inbox",
+                "options": {
+                    "host": "smtp.gmail.com",
+                    "port": 587,
+                    "tls": True,
+                    "user": "you@gmail.com",
+                    "password": os.environ["SMTP_PASSWORD"],
+                    "sender": "you@gmail.com",
+                    "to": ["you@gmail.com", "teammate@example.com"],
+                },
+                "min_level": "error",
+            }
+        ]
+    },
+    alert_rules=["isnan(loss) => critical: loss diverged"],
+)
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `host` | — | SMTP server, **required** |
+| `to` | — | one address or a list, **required** |
+| `port` | 465 with `ssl`, else 25 | |
+| `tls` | `false` | STARTTLS on a plain connection (port 587) |
+| `ssl` | `false` | implicit TLS from the start (port 465) |
+| `user` / `password` | — | omit both for an unauthenticated relay |
+| `sender` | `user`, else `expr-tracker` | the `From` address |
+| `html` | `true` | send the HTML part as well as the text |
+
+Use `tls` **or** `ssl`, not both: `tls` upgrades a plain connection, `ssl` starts
+encrypted.
+
+!!! warning "Keep the password out of your code"
+    Read it from the environment, as above. Gmail additionally rejects account
+    passwords for SMTP — turn on 2-step verification and create an
+    [app password](https://myaccount.google.com/apppasswords), which you can
+    revoke independently of your account.
+
+Mail is sent as `multipart/alternative`: a severity-coloured HTML card with the
+fields as a table, plus the plain text as a fallback for clients that will not
+render HTML. Set `html: false` for text only.
+
+Common servers:
+
+| Provider | host | port | setting |
+| --- | --- | --- | --- |
+| Gmail | `smtp.gmail.com` | 587 | `tls: true` (app password required) |
+| Outlook / Office 365 | `smtp.office365.com` | 587 | `tls: true` |
+| QQ / 163 | `smtp.qq.com`, `smtp.163.com` | 465 | `ssl: true` (authorisation code) |
+| SendGrid | `smtp.sendgrid.net` | 587 | `tls: true`, user `apikey` |
+| Internal relay | your host | 25 | often no `user`/`password` |
+
 ### Routing
 
 Each channel filters independently:

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/docs/reference/configuration.md

@@ -79,6 +79,7 @@ alert:
 | `levels` | an exact allowlist, overriding `min_level` |
 | `tags` | deliver only if the message tags intersect |
 | `options` | backend-specific settings |
+| `options.html` | email only: send an HTML part alongside the text (default `true`) |
 | `policy` | overrides the default delivery policy |
 
 ### Delivery policy
@@ -104,7 +105,7 @@ alert:
 | `condition` | — | the expression (alias: `expr`) |
 | `name` | derived | identifies the rule (alias: `alert`) |
 | `level` | `warning` | `debug`, `info`, `warning`, `error`, `critical` |
-| `title` / `message` | derived | supports templates |
+| `title` / `message` | derived | supports templates; the title defaults to `name` when you set one, else to the condition |
 | `mode` | `"edge"` | `edge` fires on transition, `level` keeps firing |
 | `for_steps` | 1 | must hold this many consecutive steps (alias: `for`) |
 | `cooldown` | 300.0 | seconds between repeats in level mode |

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/docs/reference/expressions.md

@@ -30,9 +30,44 @@ Precedence is `or < and < not < comparison < +- < */%`.
 
 ## Metric names
 
-- Bare names: `loss`, `grad_norm`.
-- `.` resolves to `/`: `eval.acc` finds the metric `eval/acc`.
-- Backticks for anything else: `` `a-b c` ``, `` `中文指标` ``.
+Bare names may contain letters, digits, `_`, `.`, `@` and `/`, so the names ML code
+actually uses need no ceremony:
+
+```
+train/loss > 1
+val/m1/acc@16 < 0.5
+mean(train/loss[20]) > 1
+```
+
+`.` also resolves to `/`, so `eval.acc` finds `eval/acc` if no metric is literally
+called `eval.acc`.
+
+### `/` is part of a name unless it is spaced
+
+A `/` joins the name when a name character follows it immediately. Division must
+therefore be written with spaces:
+
+| Written | Means |
+| --- | --- |
+| `a/b` | the metric `a/b` |
+| `a / b` | `a` divided by `b` |
+| `a /b`, `a/ b` | `a` divided by `b` (any space makes it division) |
+| `loss/2` | the metric `loss/2` |
+| `loss / 2` | `loss` divided by 2 |
+| `1/2` | division — a name cannot start with a digit |
+
+### Quote anything else
+
+A name with spaces or other characters must be quoted, with `"`, `'` or `` ` ``:
+
+```
+"train loss" > 1
+'val acc@16' < 0.5
+`a-b` > 1
+```
+
+Quotes only ever produce a metric name; the language has no string literals.
+`to_source()` renders with `"` (or another quote if the name contains one).
 
 ## Windows
 

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/pyproject.toml

@@ -1,9 +1,35 @@
 [project]
 name = "expr_tracker"
-description = "Add your description here"
+description = "Local-first experiment tracking with queryable history and expression-based alerts on your training metrics"
 readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "HSPK", email = "whxway@whu.edu.cn" }]
 requires-python = ">=3.10"
+keywords = [
+    "machine-learning",
+    "experiment-tracking",
+    "mlops",
+    "monitoring",
+    "alerting",
+    "training",
+    "deep-learning",
+    "wandb",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
 dependencies = [
     "click>=8.1.0",
     "loguru>=0.7.3",
@@ -27,6 +53,13 @@ all = [
     "polars>=0.20",
 ]
 
+[project.urls]
+Homepage = "https://hspk.github.io/expr_tracker/"
+Documentation = "https://hspk.github.io/expr_tracker/"
+Repository = "https://github.com/HSPK/expr_tracker"
+Issues = "https://github.com/HSPK/expr_tracker/issues"
+Changelog = "https://github.com/HSPK/expr_tracker/releases"
+
 [project.scripts]
 et = "expr_tracker.cli:main"
 

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/src/expr_tracker/alerts/backends/__init__.py

@@ -13,6 +13,7 @@ from .base import (
     create_backend,
     post_json,
     register_backend,
+    render_html,
     render_text,
 )
 
@@ -189,7 +190,10 @@ class EmailBackend(AlertBackend):
         mail["Subject"] = f"[{message.level.value}] {message.title}"
         mail["From"] = options.get("sender") or options.get("user") or "expr-tracker"
         mail["To"] = ", ".join(recipients)
-        mail.set_content(render_text(message))
+        # multipart/alternative: rich clients show the card, the rest see the text
+        mail.set_content(f"{message.title}\n\n{render_text(message)}")
+        if options.get("html", True):
+            mail.add_alternative(render_html(message), subtype="html")
         policy_timeout = self.config.policy.timeout if self.config.policy else 10.0
         try:
             factory = smtplib.SMTP_SSL if options.get("ssl") else smtplib.SMTP

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/src/expr_tracker/alerts/backends/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import html
 import json
 import urllib.error
 import urllib.parse
@@ -85,7 +86,7 @@ def post_json(
 
 def render_text(message: AlertMessage, include_fields: bool = True) -> str:
     """Render a message as plain text for channels without rich cards."""
-    parts = [message.text]
+    parts = [message.subtitle, message.text] if message.subtitle else [message.text]
     if include_fields and message.fields:
         parts.append("")
         parts.extend(f"{key}: {value}" for key, value in message.fields.items())
@@ -97,6 +98,74 @@ def render_text(message: AlertMessage, include_fields: bool = True) -> str:
     return "\n".join(parts)
 
 
+LEVEL_COLORS = {
+    "debug": "#616161",
+    "info": "#0288d1",
+    "warning": "#ed6c02",
+    "error": "#d32f2f",
+    "critical": "#b71c1c",
+}
+
+
+def render_html(message: AlertMessage) -> str:
+    """Render a message as self-contained HTML for email.
+
+    Everything is inline-styled and table-based: mail clients strip stylesheets,
+    and several of them ignore ``div`` layout entirely.
+    """
+    color = LEVEL_COLORS.get(message.level.value, "#616161")
+    esc = html.escape
+    rows = "".join(
+        f'<tr><td style="padding:4px 12px 4px 0;color:#666;'
+        f'white-space:nowrap;vertical-align:top">{esc(str(key))}</td>'
+        f'<td style="padding:4px 0;color:#111">{esc(str(value))}</td></tr>'
+        for key, value in message.fields.items()
+    )
+    blocks = [
+        f'<tr><td style="background:{color};padding:14px 20px;color:#fff">'
+        f'<div style="font-size:17px;font-weight:600">{esc(message.title)}</div>'
+        f'<div style="font-size:12px;opacity:.85;text-transform:uppercase;'
+        f'letter-spacing:.05em">{esc(message.level.value)}'
+        + (f" &middot; {esc(message.subtitle)}" if message.subtitle else "")
+        + "</div></td></tr>"
+    ]
+    if message.text:
+        blocks.append(
+            '<tr><td style="padding:18px 20px 0;font-size:14px;line-height:1.5;'
+            f'color:#111">{esc(message.text)}</td></tr>'
+        )
+    if rows:
+        blocks.append(
+            '<tr><td style="padding:16px 20px 0"><table cellpadding="0" '
+            f'cellspacing="0" style="font-size:13px">{rows}</table></td></tr>'
+        )
+    if message.traceback:
+        blocks.append(
+            '<tr><td style="padding:16px 20px 0"><pre style="margin:0;padding:12px;'
+            "background:#f6f6f6;border-radius:4px;font-size:12px;overflow:auto;"
+            f'white-space:pre-wrap">{esc(message.traceback)}</pre></td></tr>'
+        )
+    if message.link:
+        link = esc(message.link)
+        blocks.append(
+            f'<tr><td style="padding:18px 20px 0"><a href="{link}" '
+            f'style="display:inline-block;padding:8px 16px;background:{color};'
+            'color:#fff;text-decoration:none;border-radius:4px;font-size:13px">'
+            "Open run</a></td></tr>"
+        )
+    blocks.append('<tr><td style="padding:20px"></td></tr>')
+    return (
+        '<html><body style="margin:0;background:#f4f4f4;'
+        'font-family:-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif">'
+        '<table cellpadding="0" cellspacing="0" width="100%" '
+        'style="background:#f4f4f4;padding:24px 0"><tr><td align="center">'
+        '<table cellpadding="0" cellspacing="0" width="520" '
+        'style="background:#fff;border-radius:6px;overflow:hidden;max-width:520px">'
+        + "".join(blocks)
+        + "</table></td></tr></table></body></html>"
+    )
+
+
 def _parse_retry_after(value) -> float | None:
     try:
         return float(value)

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/src/expr_tracker/alerts/engine.py

@@ -209,7 +209,12 @@ class AlertEngine:
         except Exception as e:  # pragma: no cover - format_map already tolerates gaps
             logger.warning(f"Failed to render message for rule {rule.name!r}: {e}")
             rendered = rule.condition
-        title = _format(rule.title, values) if rule.title else rule.name
+        if rule.title:
+            title = _format(rule.title, values)
+        else:
+            # An auto-generated name is a hash; the condition says far more,
+            # especially as an email subject line
+            title = rule.condition if getattr(rule, "auto_named", False) else rule.name
         level = AlertLevel.INFO if recovered else rule.level
         message = AlertMessage(
             title=f"[recovered] {title}" if recovered else title,

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/src/expr_tracker/alerts/expr/lexer.py

@@ -11,6 +11,7 @@ OP = "OP"
 EOF = "EOF"
 
 KEYWORDS = {"and", "or", "not", "true", "false"}
+QUOTES = "\"'`"
 TWO_CHAR_OPS = {">=", "<=", "==", "!=", "&&", "||"}
 ONE_CHAR_OPS = set("><+-*/%()[],|&!~")
 DURATION_UNITS = (
@@ -51,10 +52,10 @@ def tokenize(source: str) -> list[Token]:
             i += 1
             continue
         start = i
-        if ch == "`":
-            end = source.find("`", i + 1)
+        if ch in QUOTES:
+            end = source.find(ch, i + 1)
             if end < 0:
-                raise ExprSyntaxError("Unterminated `identifier`", source, i)
+                raise ExprSyntaxError(f"Unterminated {ch}quoted name{ch}", source, i)
             tokens.append(Token(NAME, source[i + 1 : end], start))
             i = end + 1
             continue
@@ -69,8 +70,7 @@ def tokenize(source: str) -> list[Token]:
                 tokens.append(Token(NUMBER, float(text), start))
             continue
         if ch.isalpha() or ch == "_":
-            while i < n and (source[i].isalnum() or source[i] in "_."):
-                i += 1
+            i = scan_name(source, i)
             word = source[start:i]
             tokens.append(
                 Token(
@@ -110,6 +110,25 @@ def parse_duration(text: str) -> float:
         ) from e
 
 
+def is_name_char(ch: str) -> bool:
+    return ch.isalnum() or ch in "_.@"
+
+
+def scan_name(source: str, i: int) -> int:
+    """Consume a metric name, which may contain ``/`` as in ``val/m1/acc@16``.
+
+    A ``/`` only joins the name when a name character follows it immediately, so
+    division has to be spaced: ``a / b`` divides, ``a/b`` is one metric.
+    """
+    n = len(source)
+    while i < n and (
+        is_name_char(source[i])
+        or (source[i] == "/" and i + 1 < n and is_name_char(source[i + 1]))
+    ):
+        i += 1
+    return i
+
+
 def _scan_number(source: str, i: int) -> int:
     n = len(source)
     while i < n and (source[i].isdigit() or source[i] == "."):

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/src/expr_tracker/alerts/expr/nodes.py

@@ -113,7 +113,7 @@ class MetricRef(Node):
     name: str
 
     def to_source(self) -> str:
-        return self.name if _is_plain(self.name) else f"`{self.name}`"
+        return self.name if _is_plain(self.name) else _quote(self.name)
 
     def metrics(self) -> set[str]:
         return {self.name}
@@ -342,9 +342,27 @@ def _wrap(node: Node, parent_op: str | None = None) -> str:
 
 
 def _is_plain(name: str) -> bool:
+    """Whether the name can be written bare and lex back to exactly itself."""
+    from .lexer import is_name_char
+
     if not name or not (name[0].isalpha() or name[0] == "_"):
         return False
-    return all(ch.isalnum() or ch in "_." for ch in name)
+    for index, ch in enumerate(name):
+        if is_name_char(ch):
+            continue
+        # A `/` only joins the name when a name character follows it
+        if ch == "/" and index + 1 < len(name) and is_name_char(name[index + 1]):
+            continue
+        return False
+    return True
+
+
+def _quote(name: str) -> str:
+    """Wrap a name in whichever quote it does not already contain."""
+    for quote in ('"', "'", "`"):
+        if quote not in name:
+            return f"{quote}{name}{quote}"
+    return f'"{name}"'  # pragma: no cover - a name with all three quote styles
 
 
 def _format_duration(seconds: float | None) -> str:

{expr_tracker-0.2.0 → expr_tracker-0.2.2}/src/expr_tracker/alerts/models.py

@@ -230,6 +230,9 @@ class AlertRule:
                 f"Unknown alert rule mode {self.mode!r}; use 'edge' or 'level'."
             )
         self.for_steps = max(1, int(self.for_steps))
+        # A generated name identifies the rule but reads badly as a headline, so
+        # remember whether the user chose it. Not a field: it stays out of to_dict().
+        self.auto_named = not self.name
         if not self.name:
             self.name = f"rule_{self._auto_digest()}"
         if not self.message: