vqlab 0.1.0__py3-none-any.whl

vqlab/__init__.py

@@ -0,0 +1,79 @@
+"""VQLab: size-targeted vector-quantized builds of large models on Apple
+Silicon (MLX), and MTP speculative decoding over stock mlx-lm.
+
+    import vqlab
+    vqlab.use_knurlogic_arch()      # deepseek_v4 / qwen4_exp / Knurlogic's edits
+    from mlx_lm import load
+    from vqlab import load_mtp_head, mtp_generate
+
+    model, tok = load(path, trust_remote_code=True)
+    head, _ = load_mtp_head(model, model_path=path)
+    print(mtp_generate(model, tok, "Explain VQ.", head, temp=0.7))
+
+`import vqlab` changes nothing outside vqlab: the only bare import names
+it answers for are the runtime stems (vq_switch, vq_dense, ...), aliases of
+vqlab.runtime.<stem>. `use_knurlogic_arch()` is the
+opt-in: it puts a finder on sys.meta_path so `mlx_lm.models.<name>` resolves
+to Knurlogic's vendored architectures (needed to load deepseek_v4 and
+qwen4_exp, which stock mlx-lm lacks). It is idempotent, and
+VQLAB_VENDORED_ARCH=0 turns it off. Every `vqlab` CLI command calls it.
+
+See README.md and METHODOLOGY.md.
+"""
+
+__version__ = "0.1.0"
+
+from . import _layout  # noqa: F401  stage folders + pre-split import names
+from .core.box import arch_finder as _arch
+
+
+def use_knurlogic_arch() -> bool:
+    """Serve Knurlogic's architectures (deepseek_v4, qwen4_exp, and its
+    qwen3_5 / gemma4 / glm5_next) as mlx_lm.models.<name>. Call it before
+    mlx_lm.load. Idempotent; returns False when VQLAB_VENDORED_ARCH=0 or
+    knurlogic is not installed (stock mlx-lm then serves every name)."""
+    return _arch.install_arch_finder()
+
+
+def _main_is_vqlab() -> bool:
+    """True when the running program is one of vqlab's own scripts
+    (`python -m vqlab.<stage>.<tool>` or `python <pkg>/<stage>/<tool>.py`):
+    those are vqlab's entry points, and they load models as the CLI does."""
+    import os
+    import sys
+    argv = list(getattr(sys, "orig_argv", None) or [])
+    for i, a in enumerate(argv[1:], 1):
+        if a == "-m":
+            nxt = argv[i + 1] if i + 1 < len(argv) else ""
+            return nxt == "vqlab" or nxt.startswith("vqlab.")
+        if a.startswith("-m"):
+            return a[2:] == "vqlab" or a[2:].startswith("vqlab.")
+        if a.startswith("-"):
+            if a in ("-c",):
+                return False
+            continue
+        pkg = os.path.dirname(os.path.realpath(__file__))
+        return os.path.realpath(a).startswith(pkg + os.sep)
+    return False
+
+
+if _main_is_vqlab():
+    use_knurlogic_arch()
+
+
+# The MTP surface loads mlx, so it resolves on first use (PEP 562): a plain
+# `import vqlab` -- and `import vqlab.api`, the stable library/MCP surface --
+# stays free of mlx. `from vqlab import load_mtp_head` works as before.
+_MTP_NAMES = ("FAMILIES", "FamilySpec", "MTPResponse", "load_mtp_head",
+              "mtp_generate", "mtp_stream_generate", "register")
+
+
+def __getattr__(name):
+    if name in _MTP_NAMES:
+        from . import mtp
+        return getattr(mtp, name)
+    raise AttributeError(f"module 'vqlab' has no attribute {name!r}")
+
+
+__all__ = ["use_knurlogic_arch", "FAMILIES", "FamilySpec", "MTPResponse", "load_mtp_head",
+           "mtp_generate", "mtp_stream_generate", "register", "__version__"]

vqlab/_layout.py

@@ -0,0 +1,225 @@
+"""Names shipped text depends on, and the locators that find a module as a FILE.
+
+Every module has ONE canonical dotted name: its path under src/vqlab
+(`vqlab.runtime.vq_switch`, `vqlab.fit.fit_moe`). PERMANENT lists the only
+other spellings, kept forever because shipped text names them:
+
+  * every runtime/*.py stem, as `vqlab.<stem>` AND bare `<stem>`: the
+    SHIPPED runtime text (vq_dense.py's _resolve_kernel, dense_shim.py) and
+    published model.py files name them, and inside a bundle the files sit
+    flat beside model.py. Must stay byte-identical, so the names must stay;
+  * `vqlab.mtp_head*`, `vq_397b_codes` and `pack_artifact`: archived queue
+    files and ledgers name them.
+
+Whatever name is used, the result is the SAME module object (_Alias): two
+copies of vq_switch would mean two kernel caches and two sets of flag
+globals.
+
+Locators, for code that reads a module as a FILE rather than importing it:
+
+    find("smoke.py")               -> path of any tool (and vq_397b_codes.py)
+    runtime_file("vq_switch.py")   -> the repo runtime a bundle is spliced from
+    corpus("prose")                -> a house referee corpus
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.machinery
+import importlib.util
+import pathlib
+import sys
+
+PKG = pathlib.Path(__file__).resolve().parent
+SRC = PKG.parent
+
+PERMANENT = {
+    'arch_resolve': 'vqlab.runtime.arch_resolve',
+    'dense_shim': 'vqlab.runtime.dense_shim',
+    'gated_delta_chunked': 'vqlab.runtime.gated_delta_chunked',
+    'glm5_shim': 'vqlab.runtime.glm5_shim',
+    'runtime_profile': 'vqlab.runtime.runtime_profile',
+    'vq_dense': 'vqlab.runtime.vq_dense',
+    'vq_pack': 'vqlab.runtime.vq_pack',
+    'vq_switch': 'vqlab.runtime.vq_switch',
+    'vqlab.arch_resolve': 'vqlab.runtime.arch_resolve',
+    'vqlab.build.pack_artifact': 'vqlab.build.pack',
+    'vqlab.dense_shim': 'vqlab.runtime.dense_shim',
+    'vqlab.fit.vq_397b_codes': 'vqlab.fit.fit_moe',
+    'vqlab.gated_delta_chunked': 'vqlab.runtime.gated_delta_chunked',
+    'vqlab.glm5_shim': 'vqlab.runtime.glm5_shim',
+    'vqlab.mtp_head': 'vqlab.mtp.mtp_head',
+    'vqlab.mtp_head_ds4': 'vqlab.build.mtp_head_ds4',
+    'vqlab.mtp_head_glm5': 'vqlab.mtp.mtp_head_glm5',
+    'vqlab.mtp_head_qwen35': 'vqlab.mtp.mtp_head_qwen35',
+    'vqlab.pack_artifact': 'vqlab.build.pack',
+    'vqlab.runtime_profile': 'vqlab.runtime.runtime_profile',
+    'vqlab.vq_397b_codes': 'vqlab.fit.fit_moe',
+    'vqlab.vq_dense': 'vqlab.runtime.vq_dense',
+    'vqlab.vq_pack': 'vqlab.runtime.vq_pack',
+    'vqlab.vq_switch': 'vqlab.runtime.vq_switch',
+}
+
+assert not {"queue", "vqlab.queue"} & set(PERMANENT)   # stdlib `queue` stays the stdlib's
+
+# Old FILENAMES the PERMANENT names imply (vq_397b_codes.py -> fit_moe.py,
+# pack_artifact.py -> pack.py): archived queue files and ledgers name them.
+FILE_NAMES = {k.rpartition(".")[2]: v.rpartition(".")[2] for k, v in PERMANENT.items()
+               if k.rpartition(".")[2] != v.rpartition(".")[2]}
+
+
+# Folders find() searches, in order: a current filename needs no table.
+_FIND_DIRS = ("", "runtime", "core", "core/artifacts", "core/source", "core/box",
+              "family", "plan", "fit", "build", "bundle",
+              "gate", "score", "bench", "records", "ship", "agents", "mtp",
+              "queue", "selftest", "skipzero", "ops", "util", "score/referee")
+
+
+def find(name: str) -> pathlib.Path:
+    """Path of a module FILE by its filename or relative path. The old
+    filenames PERMANENT implies (vq_397b_codes.py) map to their module."""
+    stem, dot, ext = name.rpartition("/")[2].partition(".")
+    new = FILE_NAMES.get(stem)
+    if new and ext == "py":
+        name = name[:len(name) - len(stem + dot + ext)] + new + dot + ext
+    for d in _FIND_DIRS:
+        p = PKG / d / name
+        if p.exists():
+            return p
+    if name.startswith("referee/"):                 # old relative spelling
+        return find(name.split("/", 1)[1])
+    raise FileNotFoundError(f"vqlab: no module file {name!r} under {PKG}")
+
+
+def runtime_file(name: str) -> pathlib.Path:
+    """The repo's copy of a shipped runtime file (vq_switch.py, vq_dense.py,
+    vq_pack.py, dense_shim.py, glm5_shim.py). This is the text bundlers
+    splice and check-bundle compares against; its flag DEFAULTS are the
+    repo's, so a caller that needs a specific profile applies it with
+    runtime_profile.apply_profile / resolve_runtime."""
+    p = PKG / "runtime" / name
+    if not p.exists():
+        raise FileNotFoundError(f"vqlab: {name} is not a runtime file ({p})")
+    return p
+
+
+CORPORA = {"prose": "referee_corpus.txt",
+           "code": "referee_corpus_code_public.txt",
+           "lit": "referee_corpus_literary.txt"}
+_CORPUS_ALIAS = {"wikitext": "prose", "code-public": "code", "literary": "lit"}
+
+
+def corpus(name: str = "prose") -> pathlib.Path:
+    """A house referee corpus by NAME (prose / code / lit), never by a path
+    built from __file__: a scratch script that hardcodes the repo layout
+    breaks silently when the layout moves (night 4, 2026-09-26). A path
+    argument is passed through legacy_path, so old spellings still resolve."""
+    key = _CORPUS_ALIAS.get(name, name)
+    if key in CORPORA:
+        p = PKG / "score" / "referee" / CORPORA[key]
+    else:
+        p = pathlib.Path(legacy_path(str(name)))
+    if not p.is_file():
+        raise FileNotFoundError(f"vqlab: no corpus {name!r} (have {sorted(CORPORA)})")
+    return p
+
+
+def legacy_path(p):
+    """Map a path recorded BEFORE the stage split onto its new home.
+
+    Teacher caches store their corpus path in meta.json (absolute or
+    repo-relative) and shell chains pass corpora by path; both still name
+    src/vqlab/referee/. Existing paths are returned unchanged."""
+    s = str(p)
+    if pathlib.Path(s).exists():
+        return p
+    # "vqlab/referee/" (no src/) also covers an INSTALLED package's site-packages path
+    for old, new in (("vqlab/referee/", "vqlab/score/referee/"),):
+        if old in s:
+            cand = s.replace(old, new)
+            if pathlib.Path(cand).exists() or not pathlib.Path(s).is_absolute():
+                return type(p)(cand) if not isinstance(p, str) else cand
+    return p
+
+
+class _Alias(importlib.abc.MetaPathFinder, importlib.abc.Loader):
+    """ONE module object per module, whatever name it is imported by.
+
+    Without this, `import vq_switch` and `vqlab.runtime.vq_switch` load the
+    file twice: two kernel caches, two sets of env-flag globals, and a test
+    that reloads one name silently leaves the other untouched.
+
+    It answers ONLY for the PERMANENT names: `vqlab.*` spellings (our
+    namespace) and the bare runtime stems a bundle's runtime text refers to
+    (vq_switch, vq_dense, ...). Every other name gets None from it, so it
+    cannot shadow another package's module.
+
+    It sits FIRST on sys.meta_path, and that is required, not habit: a
+    script directory holding a copy of vq_switch.py (sys.path[0]) would
+    otherwise give the runtime a second module object.
+    """
+
+    def __init__(self):
+        self.map = PERMANENT
+        self._fresh = set()     # ids of modules create_module just imported
+
+    def _canon(self, fullname):
+        return self.map.get(fullname)
+
+    def find_spec(self, fullname, path=None, target=None):
+        new = self._canon(fullname)
+        if new is None or new == fullname:
+            return None
+        t = importlib.util.find_spec(new)
+        return importlib.util.spec_from_loader(
+            fullname, self, origin=t.origin if t else f"alias of {new}")
+
+    def create_module(self, spec):
+        mod = importlib.import_module(self._canon(spec.name))
+        sys.modules[spec.name] = mod
+        self._fresh.add(id(mod))
+        return mod
+
+    def exec_module(self, module):
+        """First import: the canonical import already executed it. RELOAD
+        (importlib.reload by the alias name, which is how the flag tests
+        re-read env defaults) must genuinely re-execute. Either way the
+        module keeps its CANONICAL identity; the import system just stamped
+        the alias spec on it."""
+        name = module.__spec__.name
+        canon = self._canon(name) or name
+        # Ask the path finder for the FILE's spec. importlib.util.find_spec
+        # would return the module's current __spec__ -- the alias spec the
+        # import system just stamped on it -- and recurse back into us.
+        parent, _, _ = canon.rpartition(".")
+        spec = importlib.machinery.PathFinder.find_spec(
+            canon, importlib.import_module(parent).__path__)
+        if id(module) in self._fresh:
+            self._fresh.discard(id(module))
+        else:
+            spec.loader.exec_module(module)
+        module.__spec__, module.__name__, module.__loader__ = (
+            spec, spec.name, spec.loader)
+
+    # `python -m vqlab.<old name>` goes through runpy, which asks the loader
+    # for code rather than a module. Hand it the real module's code.
+    def _target(self, fullname):
+        return importlib.util.find_spec(self._canon(fullname))
+
+    def get_code(self, fullname):
+        t = self._target(fullname)
+        return t.loader.get_code(t.name)
+
+    def get_source(self, fullname):
+        t = self._target(fullname)
+        return t.loader.get_source(t.name)
+
+    def is_package(self, fullname):
+        return False
+
+
+def install_import_aliases():
+    if not any(isinstance(f, _Alias) for f in sys.meta_path):
+        sys.meta_path.insert(0, _Alias())   # first: see _Alias docstring
+
+install_import_aliases()

vqlab/agents/CONTEXT.md

@@ -0,0 +1,50 @@
+# agents/ — Agents: the lab over MCP
+
+## Inputs
+JSON-RPC over stdio (`mcp`). (Queue files: `queue/`, untangle step 12.)
+
+## Process
+`vqlab mcp`: `where_is`, `list_artifacts`, `run` (allowlisted, detached, under the GPU lease), `next_f_number` (reserve=true before a long run), `findings_append`, ...
+
+The server is the package `mcp/` (untangle step 13), and since step 16b it is a THIN ADAPTER: each tool is a JSON schema plus an argument mapping onto `vqlab.api` (or `vqlab.ops` where the api deliberately has no call: `run` returns the launcher's raw record, `artifact_config`, `read_doc`, `queue_status`). No lab logic lives here; the implementations are in `src/vqlab/ops/` (see its CONTEXT.md). `mcp/server.py` (stdio JSON-RPC loop + the tool table: name -> fn, schema; `--supervise` delegates to `vqlab.ops.supervisor`), `mcp/common.py` (`ToolError` = `vqlab.ops.errors.LabError` = `api.ApiError`), `mcp/tools_storage.py`, `mcp/tools_runs.py`, `mcp/tools_findings.py` (the `t_*` adapters). Patch and import the defining `vqlab.ops.*` module, never an adapter.
+
+`vqlab lab scratch reclaimable` (`scratch.py`) surveys the scratch root, or each `--root` (HDD folders too), by evidence class. `packed`: an unpacked dir whose verified pack's build record names it. `preflight`: `<preflight_dir>/<queue>` copies whose queue (state.json, read through `queue.report.live_status` / `runner_pid`) is finished with no live runner, or whose queue record is gone. `fits`: dirs whose every safetensors holds only VQ triples already filed in the fit store (fit_id + size from `fit_store.read_index`, then tensor bytes against the filed copy; `--full` re-hashes the filed copy). `caches`: unregistered KL caches sha256-identical to a registered one (`registry.teacher_caches`); a registered cache is always KEPT. `campaigns`: `F###-name` folders whose finding is in the log, ARCHIVE candidates only. Each item carries its evidence (`--json`: `cls`, `evidence`, `detail`); every other top-level dir is reported KEPT with the reason; anything a symlink (roots + models) resolves into is kept. It prints the rm lines and never deletes. `reclaimable()` is the `packed` class alone (the GUI's).
+
+`vqlab queue run <file>` (code in `queue/`, see its CONTEXT.md): a multi-step campaign (a night of scoring) run from a git worktree PINNED at one commit, holding the same GPU lease as `run`, retrying resumable builds, refusing unsmoked pins, and failing a step on a nonzero exit, a traceback, or missing output. `--preflight` runs every step's small real version first; `--detach` survives the shell. `queue status` (and MCP `queue_status`) prints an ETA from the running step's own progress lines (fit-moe `[i/N] shard (Ts)`, kl-ladder cells) or past passed runs of the same step, else "ETA unknown". `--on BOX` first checks over ssh that every path the queue names exists AND reads on that box (an SMB mount can list while reads fail EIO), and refuses with the fix ("remount <volume> on <box>").
+
+`vqlab reserve` (`queue/reserve.py`) `BOX|here --for WHO --until +3h|HH:MM [--note]`, `--list`, `--release`: intent, not a lock. Stored in `<scratch>/vqlab-reservations.json` (the shared SSD every box mounts; `$VQLAB_RESERVATIONS` overrides; falls back to `~/.vqlab/reservations.json`, local-only, when scratch is unreachable). Expired ones are ignored. MCP `gpu_state` lists every box's; `queue run` / `queue run --on BOX` refuse a box reserved for someone other than `$VQLAB_WHO` (else login) unless `--override-reservation`, which state.json records.
+
+`[boxes.NAME] teachers = "<path>"`: that box's local teacher copies. `config.teachers()` returns it when running ON that box (`$VQLAB_BOX`, which `--on` sets, else hostname), and `vqlab <cmd>` expands a `<teachers>/X` argument through it, so a queue step naming `<teachers>/Model` reads the local copy there.
+
+`vqlab lab config` / `lab config set KEY PATH` / `lab config init` and the GUI's Settings view share ONE implementation, `agents/settings.py` (`locations`, `validate`, `set_value`, `campaign_sizes`): validate (absolute, a directory or creatable with `--create`, writable, free space shown), then rewrite only that key's line in `[paths]`. Every location defaults under the lab folder `lab` (`$VQLAB_HOME`, `[paths] lab`, else `~/VQLab`): `<lab>/models`, `scratch`, `fits`, `records`, and `teachers` (bf16 teachers) defaults to the models folder; with no `lab` set, data already under `~/.vqlab` or `~/.local/share/vqlab` keeps resolving there. `usage()` (GUI `/api/storage/usage`) groups the locations by volume with what each holds. `records` (`$VQLAB_RECORDS`, else `<lab>/records`) holds user-written state: `FINDINGS-LOG.md` (`$VQLAB_FINDINGS_LOG` still overrides), `registry/`, `families/` (`$VQLAB_FAMILIES_DIR`), `research/`, `queues/` (`$VQLAB_QUEUE_DIR`). Accessors: `config.records()`, `findings_log()`, `registry_dir()`, `families_dir()`, `research_dir()`, `queues_dir()`. A checkout that wants the old in-repo `lab/` sets `records` to it.
+
+## Outputs
+Detached runs under the MCP runs dir, FINDINGS-LOG entries; queues under `<records>/queues/<stamp>-<name>/` (state.json, steps/NN-name/{cmd,stdout,stderr,verdict.json}).
+
+## Rules that bite
+- Use `where_is` before claiming anything is missing.
+- `run` launches through `python -m vqlab.cli`, so every agent job is in the run log.
+- A queue step never imports the live checkout: commit mid-run freely. Uncommitted src/ changes are NOT in the queue (it refuses unless --allow-dirty).
+- Every queue step needs a `preflight` block; run `--preflight` before any multi-hour queue.
+- `onboard.py` (`vqlab plan onboard`) lives here, not in plan/: it drives the MCP server's `t_run`/`t_status`. The GPU lease file logic is `core/box/gpu_lease.py`.
+
+## Files
+- `config_cmd.py`: `vqlab lab config`: show, set or initialise storage locations (over settings.py)
+- `doctor.py`: `vqlab lab doctor`: which interpreter, packages, storage and credentials a run would use, and whether a newer vqlab is out
+- `updates.py`: is a newer vqlab on PyPI (one request a day at most, cached in records; VQLAB_OFFLINE skips it); doctor and the GUI read it
+- `bug_report.py`: `vqlab lab report-bug`: a prefilled GitHub issue (versions, chip, last failed command; portable paths, no argv); prints the link, never sends
+- `model_scan.py`: `vqlab lab scan`: models already on this machine (vqlab's own roots, the Hugging Face cache, LM Studio, exo, Ollama, `[scan] extra`), tagged original / quantized / incomplete / unreadable with their vqlab family, into `<records>/registry/found.jsonl`; reads config.json and file lists only. The GUI rescans at launch and on Rescan; first run scans once
+- `first_run.py`: on a new install (no config, no location env, no older data) the first `vqlab` command creates `~/VQLab/{models,scratch,fits,records}` (bf16 teachers default to models/) and a config naming it, and says so once; `$VQLAB_NO_SETUP=1` skips it
+- `downloads.py`: the GUI's Hub downloads (`/api/downloads`, POST `/start` `/stop`): one fetch process per repo (`_fetch.py`: `snapshot_download` into `<teachers>/<org>--<name>`), progress from bytes on disk, a model scan when done; never deletes
+- `gui.py`: `vqlab lab gui`: serves the VQ Lab GUI (Library · Recipe · Jobs · Downloads · Storage: gui_static/index.html, built from gui_static/bench/bench.html) and the JSON it reads
+- `jobs.py`: the GUI's Start / Stop / Resume of `vqlab queue` runs: a confirmed, single-use plan token, then the queue CLI (never a step itself)
+- `teachers.py`: the GUI's teachers (`/api/teachers`): profiled teachers with exact per-geometry sizes, stored fits and whether a build chain exists, plus scanned originals that only need `family-profile` (POST `/api/teachers/profile`)
+- `gui_static/bench/make_jobs_snapshot.py`: regenerates the GUI's embedded jobs snapshot (bench.html / index.html)
+- `mcp/server.py`: `vqlab lab mcp`: the stdio JSON-RPC loop and the tool table (name -> fn, schema)
+- `mcp/common.py`: `ToolError` (= `vqlab.ops.errors.LabError`) 
+- `mcp/tools_storage.py`: adapters: where_is, list_artifacts, artifact_config, read_doc, disk_free
+- `mcp/tools_runs.py`: adapters: run, status, stop, list_runs, gpu_state, queue_status
+- `mcp/tools_findings.py`: adapters: next_f_number (reserve / release), findings_tail, findings_append
+- `onboard.py`: `vqlab plan onboard`: sequence a new teacher through docs/ONBOARDING.md
+- `scratch.py`: `vqlab lab scratch`: what on scratch (or any root) a human could delete or archive, by evidence class, and why
+- `settings.py`: storage settings: read, validate and write vqlab's locations (CLI and GUI share it)

vqlab/agents/__init__.py

@@ -0,0 +1 @@
+"""vqlab agents stage: see CONTEXT.md in this folder."""

vqlab/agents/_fetch.py

@@ -0,0 +1,46 @@
+"""One GUI download's own process (agents/downloads.py starts it):
+
+    python -m vqlab.agents._fetch REPO DEST LOCKFILE RCFILE PATTERN...
+
+`huggingface_hub.snapshot_download` of REPO into DEST, only the files the
+PATTERNs allow. The process holds a flock on DEST/LOCKFILE for its whole
+life, with its pid in it: the server signals a recorded pid only while that
+lock says it is still this fetch (a pid alone can be reused after a
+restart). A second fetch of the same folder exits 2 and touches nothing. It
+records how it ended in DEST/RCFILE: 0 done, 1 failed (its stderr log says
+why). A stopped or interrupted fetch (SIGTERM, ctrl-c) records nothing.
+"""
+from __future__ import annotations
+
+import fcntl
+import os
+import pathlib
+import sys
+
+from huggingface_hub import snapshot_download
+
+
+def main(argv: list[str]) -> int:
+    repo, dest, lockfile, rcfile, *allow = argv
+    d = pathlib.Path(dest)
+    lk = open(d / lockfile, "a+")         # held open until exit: the lock is the liveness
+    try:
+        fcntl.flock(lk, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        # another fetch owns this folder: its pid and exit file stay its own
+        print(f"another fetch of {d} is running; not starting a second", file=sys.stderr)
+        return 2
+    lk.truncate(0)
+    lk.write(str(os.getpid()))
+    lk.flush()
+    try:
+        snapshot_download(repo, local_dir=d, allow_patterns=allow)
+    except Exception:
+        (d / rcfile).write_text("1")
+        raise
+    (d / rcfile).write_text("0")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

vqlab/agents/bug_report.py

@@ -0,0 +1,107 @@
+"""`vqlab lab report-bug`: a GitHub issue, filled in with what a bug needs.
+
+Builds the issue body from the versions that decide behaviour (vqlab,
+Python, macOS, the chip and its memory, mlx, mlx-lm, knurlogic,
+huggingface_hub) and the last command that failed, then prints the
+new-issue link (and, with --open, opens it). Nothing is sent: the browser
+shows the issue for the user to read, edit and submit. Every path in it is
+written in its portable form (config.portable_text), and argv is left out:
+it names the user's files.
+"""
+from __future__ import annotations
+
+import argparse
+import platform
+import sys
+import urllib.parse
+
+from vqlab import config
+
+PACKAGES = ("mlx", "mlx-lm", "knurlogic", "huggingface_hub")
+MAX_URL = 7000                  # GitHub refuses longer new-issue links
+
+
+def issues_url() -> str:
+    """The project's issue tracker, from its metadata (pyproject
+    [project.urls] Issues): the installed package's, else the checkout's."""
+    from importlib.metadata import PackageNotFoundError, metadata
+    try:
+        for u in metadata("vqlab").get_all("Project-URL") or []:
+            name, _, url = u.partition(", ")
+            if name == "Issues":
+                return url
+    except PackageNotFoundError:
+        pass
+    import tomllib
+
+    from vqlab import _layout
+    pp = _layout.SRC.parent / "pyproject.toml"
+    return tomllib.loads(pp.read_text())["project"]["urls"]["Issues"]
+
+
+def environment() -> list[str]:
+    """`name: version` lines for what decides behaviour; no paths."""
+    import vqlab
+    from vqlab.agents import doctor
+    lines = [f"vqlab: {vqlab.__version__}", f"python: {platform.python_version()}",
+             f"macOS: {platform.mac_ver()[0] or platform.platform()}"]
+    m = doctor.metal_info()
+    lines.append(f"chip: {m.get('device')}, {m.get('memory_gib')} GiB" if m.get("available")
+                 else "chip: Metal unavailable")
+    lines += [f"{p}: {doctor.package_version(p) or 'not installed'}" for p in PACKAGES]
+    return lines
+
+
+def last_failure() -> dict | None:
+    """The most recent logged command that ended with an error: its name,
+    exit status and error text (portable), never its arguments."""
+    from vqlab.records import runlog
+    for r in reversed(runlog.runs()):
+        rc = (r.get("end") or {}).get("rc")
+        if rc not in (None, 0):
+            return {"cmd": r.get("cmd"), "time": r.get("time"),
+                    "rc": config.portable_text(str(rc))}
+    return None
+
+
+def body(what: str = "") -> str:
+    """The issue text: the user's description, then the facts."""
+    out = ["**What happened, and what did you expect?**", "", what or "<describe it here>", "",
+           "**Command and output** (paste them; check for anything private first)", "",
+           "```", "", "```", "", "**Environment**", "", "```", *environment(), "```"]
+    fail = last_failure()
+    if fail:
+        out += ["", "**Last failed command**", "", "```",
+                f"vqlab {fail['cmd']}  ({fail['time']})", f"exit: {fail['rc']}", "```"]
+    return "\n".join(out) + "\n"
+
+
+def new_issue_url(title: str, text: str) -> str:
+    """GitHub's prefilled new-issue link; the body is cut to fit the limit."""
+    base = issues_url().rstrip("/") + "/new?"
+    q = {"title": title, "labels": "bug", "body": text}
+    url = base + urllib.parse.urlencode(q)
+    while len(url) > MAX_URL and len(q["body"]) > 200:
+        q["body"] = q["body"][: len(q["body"]) * 3 // 4] + "\n…(cut to fit the link)\n"
+        url = base + urllib.parse.urlencode(q)
+    return url
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="vqlab lab report-bug", description=__doc__.split("\n")[0])
+    ap.add_argument("--title", default="", help="one line saying what went wrong")
+    ap.add_argument("--what", default="", help="what happened and what you expected")
+    ap.add_argument("--open", action="store_true", help="open the issue in the browser")
+    a = ap.parse_args(argv)
+    text = body(a.what)
+    url = new_issue_url(a.title or "bug: ", text)
+    print(text)
+    print(f"Open this to file it on GitHub (nothing is sent until you submit):\n{url}")
+    if a.open:
+        import webbrowser
+        webbrowser.open(url)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())