@wendellresearch-ai/benchwarmers 0.2.0 → 0.2.2

package/scripts/check_themes.py

@@ -1,103 +1,103 @@
-"""Every theme in ui/themes passes a contrast check, and defines every colour.
-
-    python scripts/check_themes.py
-
-RELEASE-PLAN.md decision 7: themes are colours only, so a theme can break
-nothing but legibility, and that is what this checks. Each pair below is text
-the dashboard draws on a ground (ui/bench.css), held to WCAG AA: 4.5 for body
-text, 3.0 for large or bold text and for non-text marks. Grounds that bench.css
-mixes from these tokens (the chip grounds) are left to the eye.
-"""
-
-from __future__ import annotations
-
-import pathlib
-import re
-import sys
-
-ROOT = pathlib.Path(__file__).resolve().parent.parent
-THEMES = ROOT / "ui" / "themes"
-
-# Every colour token a theme must set (fonts, measure and radius come from
-# the base theme's file, rainforest.css, and may be repeated).
-REQUIRED = ("ink", "ink-2", "ink-deep", "paper", "paper-2", "band", "signal", "link", "muted",
-            "line", "brand", "primary", "primary-deep", "sky", "warn", "err")
-
-# (text, ground, minimum ratio, where it appears)
-PAIRS = [
-    ("ink", "paper", 4.5, "body text"),
-    ("ink", "paper-2", 4.5, "text in panels"),
-    ("ink", "band", 4.5, "text on bands and chips"),
-    ("muted", "paper", 4.5, "secondary text"),
-    ("muted", "paper-2", 4.5, "secondary text in panels"),
-    ("link", "paper", 4.5, "links"),
-    ("link", "paper-2", 4.5, "links in panels"),
-    ("err", "paper-2", 4.5, "error text"),
-    ("warn", "paper-2", 4.5, "warning text"),
-    ("paper", "ink", 4.5, "primary button"),
-    ("on-err", "err", 4.5, "danger button"),
-    ("log-ink", "log-ground", 4.5, "onboarding log"),
-    ("ink-deep", "sky", 4.5, "'new' chip"),
-    ("brand", "paper", 3.0, "meters, step marks, button shadow"),
-    # Only for a theme with a floor (--floor, a page ground drawn as a
-    # pattern): the header and sidebar text sit on it, held to its darkest board.
-    ("ink", "floor-ground", 4.5, "header text on the floor"),
-    ("muted", "floor-ground", 4.5, "secondary text on the floor"),
-    ("link", "floor-ground", 4.5, "links on the floor"),
-]
-OPTIONAL = {"floor-ground"}
-# What bench.css falls back to when a theme leaves these out.
-FALLBACK = {"on-err": "#ffffff", "log-ink": "paper", "log-ground": "ink-deep"}
-
-
-def tokens(path: pathlib.Path) -> dict[str, str]:
-    block = re.search(r":root\s*\{(.*?)\}", path.read_text(encoding="utf-8"), re.S)
-    return dict(re.findall(r"--([\w-]+)\s*:\s*([^;]+);", block.group(1))) if block else {}
-
-
-def colour(theme: dict[str, str], name: str) -> str:
-    value = theme.get(name) or FALLBACK.get(name, "")
-    return colour(theme, value) if value in theme or value in FALLBACK else value.strip()
-
-
-def luminance(hex_colour: str) -> float:
-    h = hex_colour.lstrip("#")
-    if len(h) == 3:
-        h = "".join(c * 2 for c in h)
-    channels = [int(h[i:i + 2], 16) / 255 for i in (0, 2, 4)]
-    lin = [c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 for c in channels]
-    return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
-
-
-def ratio(a: str, b: str) -> float:
-    la, lb = sorted((luminance(a), luminance(b)), reverse=True)
-    return (la + 0.05) / (lb + 0.05)
-
-
-def check(name: str, theme: dict[str, str]) -> list[str]:
-    problems = [f"{name}: --{t} is not set" for t in REQUIRED if t not in theme]
-    for text, ground, need, where in PAIRS:
-        if ground in OPTIONAL and ground not in theme:
-            continue
-        a, b = colour(theme, text), colour(theme, ground)
-        if not (re.fullmatch(r"#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?", a or "")
-                and re.fullmatch(r"#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?", b or "")):
-            problems.append(f"{name}: {where}: --{text} or --{ground} is not a hex colour")
-            continue
-        if (r := ratio(a, b)) < need:
-            problems.append(f"{name}: {where}: --{text} on --{ground} is {r:.2f}:1, needs {need}")
-    return problems
-
-
-def main() -> int:
-    assert round(ratio("#000000", "#ffffff"), 1) == 21.0 and round(ratio("#777777", "#ffffff"), 2) == 4.48
-    files = sorted(THEMES.glob("*.css"))
-    problems = [p for f in files for p in check(f.stem, tokens(f))]
-    for p in problems:
-        print(p)
-    print(f"{len(files)} themes: " + (f"{len(problems)} problems" if problems else "all legible"))
-    return 1 if problems else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+"""Every theme in ui/themes passes a contrast check, and defines every colour.
+
+    python scripts/check_themes.py
+
+RELEASE-PLAN.md decision 7: themes are colours only, so a theme can break
+nothing but legibility, and that is what this checks. Each pair below is text
+the dashboard draws on a ground (ui/bench.css), held to WCAG AA: 4.5 for body
+text, 3.0 for large or bold text and for non-text marks. Grounds that bench.css
+mixes from these tokens (the chip grounds) are left to the eye.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+THEMES = ROOT / "ui" / "themes"
+
+# Every colour token a theme must set (fonts, measure and radius come from
+# the base theme's file, rainforest.css, and may be repeated).
+REQUIRED = ("ink", "ink-2", "ink-deep", "paper", "paper-2", "band", "signal", "link", "muted",
+            "line", "brand", "primary", "primary-deep", "sky", "warn", "err")
+
+# (text, ground, minimum ratio, where it appears)
+PAIRS = [
+    ("ink", "paper", 4.5, "body text"),
+    ("ink", "paper-2", 4.5, "text in panels"),
+    ("ink", "band", 4.5, "text on bands and chips"),
+    ("muted", "paper", 4.5, "secondary text"),
+    ("muted", "paper-2", 4.5, "secondary text in panels"),
+    ("link", "paper", 4.5, "links"),
+    ("link", "paper-2", 4.5, "links in panels"),
+    ("err", "paper-2", 4.5, "error text"),
+    ("warn", "paper-2", 4.5, "warning text"),
+    ("paper", "ink", 4.5, "primary button"),
+    ("on-err", "err", 4.5, "danger button"),
+    ("log-ink", "log-ground", 4.5, "onboarding log"),
+    ("ink-deep", "sky", 4.5, "'new' chip"),
+    ("brand", "paper", 3.0, "meters, step marks, button shadow"),
+    # Only for a theme with a floor (--floor, a page ground drawn as a
+    # pattern): the header and sidebar text sit on it, held to its darkest board.
+    ("ink", "floor-ground", 4.5, "header text on the floor"),
+    ("muted", "floor-ground", 4.5, "secondary text on the floor"),
+    ("link", "floor-ground", 4.5, "links on the floor"),
+]
+OPTIONAL = {"floor-ground"}
+# What bench.css falls back to when a theme leaves these out.
+FALLBACK = {"on-err": "#ffffff", "log-ink": "paper", "log-ground": "ink-deep"}
+
+
+def tokens(path: pathlib.Path) -> dict[str, str]:
+    block = re.search(r":root\s*\{(.*?)\}", path.read_text(encoding="utf-8"), re.S)
+    return dict(re.findall(r"--([\w-]+)\s*:\s*([^;]+);", block.group(1))) if block else {}
+
+
+def colour(theme: dict[str, str], name: str) -> str:
+    value = theme.get(name) or FALLBACK.get(name, "")
+    return colour(theme, value) if value in theme or value in FALLBACK else value.strip()
+
+
+def luminance(hex_colour: str) -> float:
+    h = hex_colour.lstrip("#")
+    if len(h) == 3:
+        h = "".join(c * 2 for c in h)
+    channels = [int(h[i:i + 2], 16) / 255 for i in (0, 2, 4)]
+    lin = [c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 for c in channels]
+    return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+
+
+def ratio(a: str, b: str) -> float:
+    la, lb = sorted((luminance(a), luminance(b)), reverse=True)
+    return (la + 0.05) / (lb + 0.05)
+
+
+def check(name: str, theme: dict[str, str]) -> list[str]:
+    problems = [f"{name}: --{t} is not set" for t in REQUIRED if t not in theme]
+    for text, ground, need, where in PAIRS:
+        if ground in OPTIONAL and ground not in theme:
+            continue
+        a, b = colour(theme, text), colour(theme, ground)
+        if not (re.fullmatch(r"#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?", a or "")
+                and re.fullmatch(r"#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?", b or "")):
+            problems.append(f"{name}: {where}: --{text} or --{ground} is not a hex colour")
+            continue
+        if (r := ratio(a, b)) < need:
+            problems.append(f"{name}: {where}: --{text} on --{ground} is {r:.2f}:1, needs {need}")
+    return problems
+
+
+def main() -> int:
+    assert round(ratio("#000000", "#ffffff"), 1) == 21.0 and round(ratio("#777777", "#ffffff"), 2) == 4.48
+    files = sorted(THEMES.glob("*.css"))
+    problems = [p for f in files for p in check(f.stem, tokens(f))]
+    for p in problems:
+        print(p)
+    print(f"{len(files)} themes: " + (f"{len(problems)} problems" if problems else "all legible"))
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/init.py

@@ -1,124 +1,124 @@
-"""Set up a data folder for a new install, and point this checkout at it.
-
-    python scripts/init.py                     # the OS's per-user data folder
-    python scripts/init.py ~/bench-data        # or one of your choosing
-    python scripts/init.py --endpoint openrouter https://openrouter.ai/api/v1 --key
-
-RELEASE-PLAN.md Phase 4, `benchwarmers init`, the small version until the
-package exists (Phase 3b brings the command). It:
-
-  1. copies `examples/` into the folder, never over a file already there, so
-     running it again on a folder in use changes nothing it holds;
-  2. makes the folder's layout (metrics/paths.py LAYOUT);
-  3. points this checkout at it (`.benchwarmers-home`), unless
-     BENCHWARMERS_HOME is set or the checkout already points elsewhere: then
-     it says what to change rather than repoint an install that has data;
-  4. with --endpoint NAME BASE_URL, adds a first endpoint by the dashboard's
-     own rules (serve.save_endpoint: saved only once BASE_URL/models answers).
-     NAME is also the key's name in the llm key store, and a key already
-     stored under it is used. --key asks for one, unechoed, and stores it
-     there; never a key on the command line, which lands in the shell's
-     history. Asked only with --key: on Windows a redirected stdin still
-     reads as a terminal, and getpass then waits on the console for ever.
-
-The rest happens in the dashboard (`python serve.py`): sign in with a
-provider or paste a key, onboard models, build a collection.
-"""
-
-from __future__ import annotations
-
-import argparse
-import getpass
-import os
-import pathlib
-import shutil
-import sys
-
-ROOT = pathlib.Path(__file__).resolve().parent.parent
-EXAMPLES = ROOT / "examples"
-POINTER = ROOT / ".benchwarmers-home"              # metrics/paths.py reads it
-
-
-def default_folder() -> pathlib.Path:
-    """The OS's per-user data folder (RELEASE-PLAN section 2): never beside the
-    code, which a package upgrade replaces."""
-    if os.name == "nt":
-        return pathlib.Path(os.environ.get("LOCALAPPDATA") or pathlib.Path.home()) / "benchwarmers"
-    if sys.platform == "darwin":
-        return pathlib.Path.home() / "Library" / "Application Support" / "benchwarmers"
-    return pathlib.Path(os.environ.get("XDG_DATA_HOME") or pathlib.Path.home() / ".local" / "share") / "benchwarmers"
-
-
-def point(folder: pathlib.Path, env: str) -> str:
-    """Make this checkout use `folder`, or say why it was left alone."""
-    if env:
-        if pathlib.Path(env).expanduser().resolve() == folder:
-            return "BENCHWARMERS_HOME already names it."
-        return f"BENCHWARMERS_HOME is set to {env}, which wins: set it to {folder} to use this folder."
-    named = POINTER.read_text(encoding="utf-8").strip() if POINTER.exists() else ""
-    if named and pathlib.Path(named).expanduser().resolve() == folder:
-        return f"This checkout already points at it ({POINTER.name})."
-    if named:
-        return (f"This checkout points at {named} ({POINTER.name}) and was left so: to use {folder},"
-                f" put that path in {POINTER} or set BENCHWARMERS_HOME to it.")
-    if folder == ROOT:
-        return "This checkout is its own data folder."
-    POINTER.write_text(f"{folder}\n", encoding="utf-8")
-    return f"This checkout points at it now ({POINTER.name})."
-
-
-def run(folder, endpoint: tuple[str, str] | None = None, secret: str = "") -> tuple[bool, list[str]]:
-    """(ok, what to tell the user)."""
-    folder = pathlib.Path(folder).expanduser().resolve()
-    env = os.environ.get("BENCHWARMERS_HOME", "").strip()
-    # Before metrics/ is imported: paths.py reads it once, and serve.save_endpoint
-    # below must write into this folder, whatever the checkout points at.
-    os.environ["BENCHWARMERS_HOME"] = str(folder)
-    sys.path[:0] = [str(ROOT), str(ROOT / "metrics")]
-    import paths
-    copied: list[str] = []
-
-    def copy_new(src, dst):
-        if not os.path.exists(dst):
-            shutil.copy2(src, dst)
-            copied.append(dst)
-    shutil.copytree(EXAMPLES, folder, dirs_exist_ok=True, copy_function=copy_new)
-    paths.make(folder)
-    said = [f"Data folder: {folder} ({len(copied)} starter file(s) copied, nothing overwritten).",
-            point(folder, env)]
-    ok = True
-    if endpoint:
-        import serve
-        if serve.DATA.resolve() != folder:         # never into another install's data
-            return False, said + [f"Endpoint not added: this process already uses {serve.DATA}."]
-        name, base = endpoint
-        r = serve.save_endpoint(name, base, secret, who="init", new=True)
-        ok = r["ok"]
-        said.append(f"Endpoint {name} added: it lists {r['served']} models. {r.get('note', '')}".strip() if ok else
-                    "Endpoint not added: " + "; ".join(r["errors"]) + ". Add it from the dashboard instead.")
-    port = os.environ.get("BENCH_PORT") or 8122
-    # From npm (bin/benchwarmers.js) the dashboard starts next by itself.
-    start = "the dashboard starts now: open" if os.environ.get("BENCHWARMERS_LAUNCHER") else "python serve.py, then open"
-    said.append(f"Next: {start} http://localhost:{port} to "
-                + ("onboard models from it." if endpoint and ok else
-                   "add an endpoint (sign in with a provider, or paste a key) and onboard models."))
-    return ok, said
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description="Set up a data folder and point this checkout at it.")
-    ap.add_argument("folder", nargs="?", help=f"default: {default_folder()}")
-    ap.add_argument("--endpoint", nargs=2, metavar=("NAME", "BASE_URL"),
-                    help="add a first OpenAI-compatible endpoint; NAME is also its key's name")
-    ap.add_argument("--key", action="store_true", help="ask for the endpoint's API key (unechoed)")
-    args = ap.parse_args()
-    if args.key and not args.endpoint:
-        ap.error("--key goes with --endpoint")
-    secret = getpass.getpass(f"API key for {args.endpoint[0]}: ").strip() if args.key else ""
-    ok, said = run(args.folder or default_folder(), args.endpoint, secret)
-    print("\n".join(said))
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+"""Set up a data folder for a new install, and point this checkout at it.
+
+    python scripts/init.py                     # the OS's per-user data folder
+    python scripts/init.py ~/bench-data        # or one of your choosing
+    python scripts/init.py --endpoint openrouter https://openrouter.ai/api/v1 --key
+
+RELEASE-PLAN.md Phase 4, `benchwarmers init`, the small version until the
+package exists (Phase 3b brings the command). It:
+
+  1. copies `examples/` into the folder, never over a file already there, so
+     running it again on a folder in use changes nothing it holds;
+  2. makes the folder's layout (metrics/paths.py LAYOUT);
+  3. points this checkout at it (`.benchwarmers-home`), unless
+     BENCHWARMERS_HOME is set or the checkout already points elsewhere: then
+     it says what to change rather than repoint an install that has data;
+  4. with --endpoint NAME BASE_URL, adds a first endpoint by the dashboard's
+     own rules (serve.save_endpoint: saved only once BASE_URL/models answers).
+     NAME is also the key's name in the llm key store, and a key already
+     stored under it is used. --key asks for one, unechoed, and stores it
+     there; never a key on the command line, which lands in the shell's
+     history. Asked only with --key: on Windows a redirected stdin still
+     reads as a terminal, and getpass then waits on the console for ever.
+
+The rest happens in the dashboard (`python serve.py`): sign in with a
+provider or paste a key, onboard models, build a collection.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import pathlib
+import shutil
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+EXAMPLES = ROOT / "examples"
+POINTER = ROOT / ".benchwarmers-home"              # metrics/paths.py reads it
+
+
+def default_folder() -> pathlib.Path:
+    """The OS's per-user data folder (RELEASE-PLAN section 2): never beside the
+    code, which a package upgrade replaces."""
+    if os.name == "nt":
+        return pathlib.Path(os.environ.get("LOCALAPPDATA") or pathlib.Path.home()) / "benchwarmers"
+    if sys.platform == "darwin":
+        return pathlib.Path.home() / "Library" / "Application Support" / "benchwarmers"
+    return pathlib.Path(os.environ.get("XDG_DATA_HOME") or pathlib.Path.home() / ".local" / "share") / "benchwarmers"
+
+
+def point(folder: pathlib.Path, env: str) -> str:
+    """Make this checkout use `folder`, or say why it was left alone."""
+    if env:
+        if pathlib.Path(env).expanduser().resolve() == folder:
+            return "BENCHWARMERS_HOME already names it."
+        return f"BENCHWARMERS_HOME is set to {env}, which wins: set it to {folder} to use this folder."
+    named = POINTER.read_text(encoding="utf-8").strip() if POINTER.exists() else ""
+    if named and pathlib.Path(named).expanduser().resolve() == folder:
+        return f"This checkout already points at it ({POINTER.name})."
+    if named:
+        return (f"This checkout points at {named} ({POINTER.name}) and was left so: to use {folder},"
+                f" put that path in {POINTER} or set BENCHWARMERS_HOME to it.")
+    if folder == ROOT:
+        return "This checkout is its own data folder."
+    POINTER.write_text(f"{folder}\n", encoding="utf-8")
+    return f"This checkout points at it now ({POINTER.name})."
+
+
+def run(folder, endpoint: tuple[str, str] | None = None, secret: str = "") -> tuple[bool, list[str]]:
+    """(ok, what to tell the user)."""
+    folder = pathlib.Path(folder).expanduser().resolve()
+    env = os.environ.get("BENCHWARMERS_HOME", "").strip()
+    # Before metrics/ is imported: paths.py reads it once, and serve.save_endpoint
+    # below must write into this folder, whatever the checkout points at.
+    os.environ["BENCHWARMERS_HOME"] = str(folder)
+    sys.path[:0] = [str(ROOT), str(ROOT / "metrics")]
+    import paths
+    copied: list[str] = []
+
+    def copy_new(src, dst):
+        if not os.path.exists(dst):
+            shutil.copy2(src, dst)
+            copied.append(dst)
+    shutil.copytree(EXAMPLES, folder, dirs_exist_ok=True, copy_function=copy_new)
+    paths.make(folder)
+    said = [f"Data folder: {folder} ({len(copied)} starter file(s) copied, nothing overwritten).",
+            point(folder, env)]
+    ok = True
+    if endpoint:
+        import serve
+        if serve.DATA.resolve() != folder:         # never into another install's data
+            return False, said + [f"Endpoint not added: this process already uses {serve.DATA}."]
+        name, base = endpoint
+        r = serve.save_endpoint(name, base, secret, who="init", new=True)
+        ok = r["ok"]
+        said.append(f"Endpoint {name} added: it lists {r['served']} models. {r.get('note', '')}".strip() if ok else
+                    "Endpoint not added: " + "; ".join(r["errors"]) + ". Add it from the dashboard instead.")
+    port = os.environ.get("BENCH_PORT") or 8122
+    # From npm (bin/benchwarmers.js) the dashboard starts next by itself.
+    start = "the dashboard starts now: open" if os.environ.get("BENCHWARMERS_LAUNCHER") else "python serve.py, then open"
+    said.append(f"Next: {start} http://localhost:{port} to "
+                + ("onboard models from it." if endpoint and ok else
+                   "add an endpoint (sign in with a provider, or paste a key) and onboard models."))
+    return ok, said
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Set up a data folder and point this checkout at it.")
+    ap.add_argument("folder", nargs="?", help=f"default: {default_folder()}")
+    ap.add_argument("--endpoint", nargs=2, metavar=("NAME", "BASE_URL"),
+                    help="add a first OpenAI-compatible endpoint; NAME is also its key's name")
+    ap.add_argument("--key", action="store_true", help="ask for the endpoint's API key (unechoed)")
+    args = ap.parse_args()
+    if args.key and not args.endpoint:
+        ap.error("--key goes with --endpoint")
+    secret = getpass.getpass(f"API key for {args.endpoint[0]}: ").strip() if args.key else ""
+    ok, said = run(args.folder or default_folder(), args.endpoint, secret)
+    print("\n".join(said))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/list_served.py

@@ -1,78 +1,78 @@
-"""List what Open WebUI actually serves, versus what the llm CLI can see.
-
-The gap between those two is the thing this script exists for. A model can be
-live in Open WebUI and completely invisible to the CLI, which reports it as
-"not configured" — indistinguishable, from the outside, from not existing.
-
-    python scripts/list_served.py             # everything, marked
-    python scripts/list_served.py nemotron    # filter by substring
-
-Output marks each served model:
-
-    [registered]   in extra-openai-models.yaml, usable now
-    [ MISSING  ]   served but unregistered — add it to the yaml
-
-The API key is read from the llm CLI's own `keys.json` and is never printed.
-"""
-
-from __future__ import annotations
-
-import json
-import pathlib
-import sys
-import urllib.request
-
-sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "metrics"))
-from paths import DATA  # noqa: E402  -- the install's data folder (metrics/paths.py)
-import endpoints  # noqa: E402
-LLM_DIR = endpoints.LLM_DIR
-REPO_YAML = DATA / "config" / "extra-openai-models.yaml"
-API_BASE = endpoints.base()   # the default endpoint; the picker covers the rest
-TIMEOUT = 30
-
-
-def registered_model_names() -> set[str]:
-    """`model_name` values from the yaml — what the endpoint is asked for.
-
-    Parsed by hand rather than with PyYAML so this script has no dependency;
-    the file is a flat list of scalar keys and that is unlikely to change.
-    """
-    text = REPO_YAML.read_text(encoding="utf-8") if REPO_YAML.exists() else ""
-    names = set()
-    for line in text.splitlines():
-        line = line.strip()
-        if line.startswith("model_name:"):
-            names.add(line.split(":", 1)[1].strip().strip('"').strip("'"))
-    return names
-
-
-def served() -> list[str]:
-    return sorted(endpoints.models(timeout=TIMEOUT))
-
-
-def main() -> int:
-    needle = sys.argv[1].lower() if len(sys.argv) > 1 else ""
-    try:
-        models = served()
-    except Exception as exc:                       # noqa: BLE001
-        print(f"could not reach {API_BASE}: {type(exc).__name__}: {exc}",
-              file=sys.stderr)
-        return 1
-
-    known = registered_model_names()
-    shown = [m for m in models if needle in m.lower()]
-    missing = 0
-    for name in shown:
-        mark = "[registered]" if name in known else "[ MISSING  ]"
-        missing += name not in known
-        print(f"  {mark}  {name}")
-
-    print(f"\n{len(shown)} shown of {len(models)} served; {missing} unregistered")
-    if missing:
-        print(f"Add the missing ones to {REPO_YAML.name}, then:"
-              f"\n  python scripts/sync_config.py")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""List what Open WebUI actually serves, versus what the llm CLI can see.
+
+The gap between those two is the thing this script exists for. A model can be
+live in Open WebUI and completely invisible to the CLI, which reports it as
+"not configured" — indistinguishable, from the outside, from not existing.
+
+    python scripts/list_served.py             # everything, marked
+    python scripts/list_served.py nemotron    # filter by substring
+
+Output marks each served model:
+
+    [registered]   in extra-openai-models.yaml, usable now
+    [ MISSING  ]   served but unregistered — add it to the yaml
+
+The API key is read from the llm CLI's own `keys.json` and is never printed.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+import urllib.request
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "metrics"))
+from paths import DATA  # noqa: E402  -- the install's data folder (metrics/paths.py)
+import endpoints  # noqa: E402
+LLM_DIR = endpoints.LLM_DIR
+REPO_YAML = DATA / "config" / "extra-openai-models.yaml"
+API_BASE = endpoints.base()   # the default endpoint; the picker covers the rest
+TIMEOUT = 30
+
+
+def registered_model_names() -> set[str]:
+    """`model_name` values from the yaml — what the endpoint is asked for.
+
+    Parsed by hand rather than with PyYAML so this script has no dependency;
+    the file is a flat list of scalar keys and that is unlikely to change.
+    """
+    text = REPO_YAML.read_text(encoding="utf-8") if REPO_YAML.exists() else ""
+    names = set()
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("model_name:"):
+            names.add(line.split(":", 1)[1].strip().strip('"').strip("'"))
+    return names
+
+
+def served() -> list[str]:
+    return sorted(endpoints.models(timeout=TIMEOUT))
+
+
+def main() -> int:
+    needle = sys.argv[1].lower() if len(sys.argv) > 1 else ""
+    try:
+        models = served()
+    except Exception as exc:                       # noqa: BLE001
+        print(f"could not reach {API_BASE}: {type(exc).__name__}: {exc}",
+              file=sys.stderr)
+        return 1
+
+    known = registered_model_names()
+    shown = [m for m in models if needle in m.lower()]
+    missing = 0
+    for name in shown:
+        mark = "[registered]" if name in known else "[ MISSING  ]"
+        missing += name not in known
+        print(f"  {mark}  {name}")
+
+    print(f"\n{len(shown)} shown of {len(models)} served; {missing} unregistered")
+    if missing:
+        print(f"Add the missing ones to {REPO_YAML.name}, then:"
+              f"\n  python scripts/sync_config.py")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())