llmt-cli 0.2.0__py3-none-any.whl

llmt/cli.py

@@ -0,0 +1,562 @@
+"""llmt — command-line client for the LLM Torrents catalog.
+
+Commands
+--------
+  search  <query>            query the catalog, print a readable table
+  pull    <slug|slug:quant>  resolve -> download via aria2c (webseeds) -> verify
+  verify  <path> <ref>       re-verify already-downloaded files, no re-download
+  seed    <slug|slug:quant>  seed an already-downloaded artifact into the swarm
+  scan                       find local models you already have and seed them
+  doctor                     diagnose why your seeds aren't actually seeding
+
+``pull``, ``verify`` and ``seed`` authenticate the catalog's Ed25519-signed
+manifest (signature checked against the public key pinned inside this
+package) before trusting any hashes; an unverifiable manifest is a hard
+error (exit 15), never a silent downgrade.
+
+All commands accept ``--json`` (machine-readable) and ``--api-base`` /
+``--api-key`` (or env ``LLMT_API_BASE`` / ``LLMT_API_KEY``). Expected failures
+print a single clean line and exit non-zero — never a traceback.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Any, Optional
+
+from . import __version__
+from .api import ApiClient, DEFAULT_API_BASE
+from .download import build_aria2c_args, ensure_aria2c, run_aria2c
+from .errors import (
+    LayoutSafetyError,
+    LicenseGatedError,
+    LlmtError,
+    NotAvailableError,
+    RateLimitedError,
+)
+from .manifest import (
+    check_catalog_consistency,
+    fetch_verified_manifest,
+    manifest_files,
+)
+from .models import (
+    files_of,
+    is_gated,
+    model_page_of,
+    parse_ref,
+    require_available_download,
+    select_quant,
+)
+from .output import emit_json, render_table
+from .verify import all_ok, resolve_catalog_path, verify_files
+from .scancmd import add_scan_args, cmd_scan
+from .doctorcmd import add_doctor_args, cmd_doctor
+from .telemetry.cmd import add_telemetry_args
+
+
+def _client(args: argparse.Namespace) -> ApiClient:
+    return ApiClient(base=args.api_base, key=args.api_key, timeout=args.timeout)
+
+
+def _verified_files(client: ApiClient, download: dict,
+                    as_json: bool) -> tuple[list[dict], dict]:
+    """Fetch the torrent's Ed25519-signed manifest, verify it against the
+    key pinned in this package, cross-check the catalog's file list against
+    it, and return (files, manifest_info) with the SIGNED manifest's files[]
+    as the hashing source of truth.
+
+    Raises :class:`~llmt.errors.ManifestVerificationError` (exit 15, fail
+    closed) on ANY failure — fetch error/offline, malformed document, bad
+    signature, wrong key, wrong torrent, or catalog/manifest disagreement.
+    """
+    info_hash = download.get("info_hash_v1") or download.get("info_hash_v2")
+    doc = fetch_verified_manifest(client, info_hash)
+    mfiles = manifest_files(doc)
+    check_catalog_consistency(files_of(download), mfiles)
+    sig = doc.get("signature") or {}
+    if not as_json:
+        print(f"Manifest signature verified: Ed25519, key id "
+              f"'{sig.get('key_id')}' (public key pinned in this llmt build).")
+    return mfiles, {"verified": True, "algo": sig.get("algo"),
+                    "key_id": sig.get("key_id")}
+
+
+# ---------------------------------------------------------------------------
+# search
+# ---------------------------------------------------------------------------
+def cmd_search(args: argparse.Namespace) -> int:
+    client = _client(args)
+    extra = {}
+    for rig in args.rig or []:
+        if "=" in rig:
+            k, v = rig.split("=", 1)
+            extra[f"rig[{k}]"] = v
+    resp = client.list_models(
+        q=args.query, fit=args.fit, per_page=args.per_page, sort=args.sort,
+        extra=extra or None,
+    )
+    data = resp.get("data", [])
+    if args.json:
+        emit_json(resp)
+        return 0
+
+    if not data:
+        print("No models matched.")
+        return 0
+
+    rows = []
+    for m in data:
+        lic = m.get("license") or {}
+        lic_str = lic.get("name") or "-"
+        if lic.get("gated"):
+            lic_str += " (gated)"
+        verdict = m.get("fit_verdict") or "-"
+        rows.append([
+            m.get("slug", "-"),
+            m.get("name", "-"),
+            _params_label(m),
+            lic_str,
+            verdict,
+        ])
+    print(render_table(
+        rows, headers=["SLUG", "NAME", "PARAMS", "LICENSE", "FIT"]
+    ))
+    meta = resp.get("meta", {}).get("pagination", {})
+    if meta:
+        print(f"\n{meta.get('to', len(data))}/{meta.get('total', len(data))} shown"
+              f" (page {meta.get('current_page', 1)}/{meta.get('last_page', 1)}).")
+    return 0
+
+
+def _params_label(m: dict) -> str:
+    """Parameter count in billions for the list view.
+
+    The compact list endpoint reports params, not per-quant file bytes, so we
+    show the honest parameter figure (e.g. "70.6B") rather than inventing a
+    download size. Actual on-disk sizes are shown per-quant by ``pull``.
+    """
+    p = m.get("params_total_b")
+    if not isinstance(p, (int, float)):
+        return "-"
+    return f"{p:.1f}B"
+
+
+# ---------------------------------------------------------------------------
+# pull
+# ---------------------------------------------------------------------------
+def cmd_pull(args: argparse.Namespace) -> int:
+    client = _client(args)
+    slug, quant_level = parse_ref(args.ref)
+    if args.quant:
+        quant_level = args.quant
+
+    model = client.get_model(slug)["data"]
+
+    # D7: refuse to go any further for a gated model — print the gate + page.
+    if is_gated(model):
+        raise LicenseGatedError(slug, model_page_of(model))
+
+    quant = select_quant(model, quant_level)
+    download = require_available_download(model, quant)  # raises gate/na
+
+    # M2: authenticate the signed manifest BEFORE moving a byte. The
+    # verified manifest's files[] (not the unauthenticated catalog block)
+    # is what the download will be checked against.
+    files, manifest_info = _verified_files(client, download,
+                                           as_json=args.json)
+
+    magnet = download.get("magnet")
+    webseeds = download.get("webseeds") or []
+    out_dir = args.output or os.path.join(os.getcwd(),
+                                          f"{slug}-{quant.get('quant_level')}")
+    os.makedirs(out_dir, exist_ok=True)
+
+    exe = ensure_aria2c()
+    argv = build_aria2c_args(
+        magnet=magnet, out_dir=out_dir, webseeds=webseeds,
+        trackers=args.tracker or [], seed=False, exe=exe,
+    )
+
+    if args.dry_run:
+        if args.json:
+            emit_json({"aria2c": argv, "out_dir": out_dir,
+                       "files": files, "webseeds": webseeds,
+                       "manifest": manifest_info})
+        else:
+            print("Would run:\n  " + " ".join(_shquote(a) for a in argv))
+            print(f"\nWebseeds ({len(webseeds)}):")
+            for w in webseeds:
+                print(f"  {w}")
+        return 0
+
+    print(f"Downloading {slug}:{quant.get('quant_level')} -> {out_dir}")
+    print(f"Using {len(webseeds)} webseed(s) + BitTorrent swarm via aria2c.")
+    rc = run_aria2c(argv)
+    if rc != 0:
+        # Known webseed-origin quirks make aria2c exit non-zero even though
+        # every payload byte arrived: the mirrors 403 the bare base URL
+        # (directory listings are disabled by design, aria2c exit 22), and
+        # hybrid torrents' BEP-47 ``.pad`` files 404 on HTTP mirrors (reported
+        # as a 98-99% stall / resource-not-found). Trust the disk, not the
+        # exit code: if every expected file is present at its expected size,
+        # proceed to the real SHA-256 verification; otherwise fail loudly.
+        if _payload_present(out_dir, files):
+            print(f"aria2c exited with code {rc}, but all {len(files)} "
+                  f"expected file(s) are present at the expected sizes "
+                  f"(known webseed base-URL/.pad quirk). "
+                  f"Proceeding to SHA-256 verification.",
+                  file=sys.stderr)
+        else:
+            print(f"aria2c exited with code {rc} and the download is "
+                  f"incomplete; skipping verification.", file=sys.stderr)
+            return 10
+
+    return _do_verify(out_dir, files, slug, quant.get("quant_level"),
+                      as_json=args.json, header="Download complete. Verifying",
+                      manifest_info=manifest_info)
+
+
+def _payload_present(base_dir: str, files: list[dict]) -> bool:
+    """True iff every expected file exists under ``base_dir`` at the expected
+    size (when one was supplied). Presence+size only — the SHA-256 pass
+    against the verified manifest that follows is still the real integrity
+    check."""
+    if not files:
+        return False
+    for f in files:
+        rel = f.get("path")
+        if not rel:
+            return False
+        try:
+            full = resolve_catalog_path(base_dir, rel)
+        except LayoutSafetyError:
+            print(f"Refusing manifest file path {rel!r}: it does not resolve "
+                  f"inside the download directory.", file=sys.stderr)
+            return False
+        if not os.path.isfile(full):
+            return False
+        size = f.get("size")
+        if size is not None and os.path.getsize(full) != size:
+            return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# verify
+# ---------------------------------------------------------------------------
+def cmd_verify(args: argparse.Namespace) -> int:
+    client = _client(args)
+    slug, quant_level = parse_ref(args.ref)
+    if args.quant:
+        quant_level = args.quant
+
+    model = client.get_model(slug)["data"]
+    if is_gated(model):
+        raise LicenseGatedError(slug, model_page_of(model))
+
+    quant = select_quant(model, quant_level)
+    download = require_available_download(model, quant)
+
+    # M2: hashes come from the SIGNATURE-VERIFIED manifest, or not at all.
+    files, manifest_info = _verified_files(client, download,
+                                           as_json=args.json)
+
+    base_dir, note = _resolve_verify_dir(args.path, files)
+    if note:
+        print(note, file=sys.stderr)
+    return _do_verify(base_dir, files, slug, quant.get("quant_level"),
+                      as_json=args.json, header="Verifying",
+                      manifest_info=manifest_info)
+
+
+def _resolve_verify_dir(path: str, files: list[dict]) -> tuple[str, Optional[str]]:
+    """Accept either the OUTER download directory (what ``pull`` created) or
+    the inner payload directory the torrent unpacked inside it.
+
+    Manifest ``files[].path`` entries are relative to the outer directory and
+    usually start with the payload directory name. If the given ``path``
+    already contains the files, use it as-is. If the user instead passed the
+    inner payload directory (its basename equals the files' common top-level
+    directory and the files resolve from its parent), verify against the
+    parent and say so. Otherwise return ``path`` unchanged plus a hint
+    naming exactly which directory to pass.
+    """
+    rels = [f.get("path") for f in files if f.get("path")]
+    if not rels:
+        return path, None
+
+    def _hits(base: str) -> int:
+        return sum(1 for r in rels if os.path.isfile(os.path.join(base, r)))
+
+    if _hits(path) > 0:
+        return path, None
+
+    tops = {r.replace("\\", "/").split("/", 1)[0]
+            for r in rels if "/" in r.replace("\\", "/")}
+    if len(tops) != 1:
+        return path, None
+    top = next(iter(tops))
+    abspath = os.path.abspath(path)
+    parent = os.path.dirname(abspath)
+    if os.path.basename(abspath) == top and _hits(parent) > 0:
+        return parent, (f"Note: '{path}' is the inner payload directory; "
+                        f"verifying against its parent '{parent}'.")
+    return path, (f"Hint: no catalog files found under '{path}'. Pass the "
+                  f"outer download directory (the one containing '{top}/').")
+
+
+def _do_verify(base_dir: str, files: list[dict], slug: str,
+               quant_level: Any, as_json: bool, header: str,
+               manifest_info: Optional[dict] = None) -> int:
+    if not files:
+        msg = (f"No files listed in the signed manifest for "
+               f"{slug}:{quant_level}.")
+        if as_json:
+            emit_json({"ok": False, "error": msg, "results": []})
+        else:
+            print(msg, file=sys.stderr)
+        return 3
+
+    if not as_json:
+        print(f"{header} {len(files)} file(s) against the Ed25519-verified "
+              f"manifest's SHA-256s ...")
+    results = verify_files(base_dir, files)
+    ok = all_ok(results)
+
+    if as_json:
+        emit_json({
+            "ok": ok, "slug": slug, "quant": quant_level,
+            "base_dir": base_dir,
+            "manifest": manifest_info or {"verified": False},
+            "results": [r.to_dict() for r in results],
+        })
+    else:
+        for r in results:
+            mark = {
+                "ok": "PASS", "mismatch": "FAIL", "missing": "MISSING",
+                "size_mismatch": "SIZE-FAIL", "no_hash": "NO-HASH",
+                "unsafe_path": "UNSAFE-PATH",
+            }.get(r.status, r.status.upper())
+            print(f"  [{mark}] {r.path}")
+            if r.status == "unsafe_path":
+                print("          path escapes the target directory — "
+                      "refused, not hashed")
+            if r.status == "mismatch":
+                print(f"          expected {r.expected}")
+                print(f"          actual   {r.actual}")
+        print()
+        print("VERIFIED OK — every file matches the Ed25519-signed manifest "
+              "(signature checked against the key pinned in this llmt build)."
+              if ok else
+              "VERIFICATION FAILED — one or more files did not match the "
+              "signed manifest.")
+    return 0 if ok else 3
+
+
+# ---------------------------------------------------------------------------
+# seed
+# ---------------------------------------------------------------------------
+def cmd_seed(args: argparse.Namespace) -> int:
+    client = _client(args)
+    slug, quant_level = parse_ref(args.ref)
+    if args.quant:
+        quant_level = args.quant
+
+    model = client.get_model(slug)["data"]
+    if is_gated(model):
+        raise LicenseGatedError(slug, model_page_of(model))
+
+    quant = select_quant(model, quant_level)
+    download = require_available_download(model, quant)
+
+    # M2: never seed a torrent whose signed manifest cannot be
+    # authenticated — raises (exit 15) before anything is handed to aria2c.
+    _verified_files(client, download, as_json=args.json)
+
+    magnet = download.get("magnet")
+    webseeds = download.get("webseeds") or []
+    seed_dir = args.path
+
+    exe = ensure_aria2c()
+    argv = build_aria2c_args(
+        magnet=magnet, out_dir=seed_dir, webseeds=webseeds,
+        trackers=args.tracker or [], seed=True, exe=exe,
+    )
+    if args.dry_run:
+        if args.json:
+            emit_json({"aria2c": argv, "seed_dir": seed_dir})
+        else:
+            print("Would run:\n  " + " ".join(_shquote(a) for a in argv))
+        return 0
+
+    print(f"Seeding {slug}:{quant.get('quant_level')} from {seed_dir} "
+          f"(Ctrl-C to stop).")
+    return run_aria2c(argv)
+
+
+def _shquote(s: str) -> str:
+    if s == "" or any(c in s for c in ' "\'\\&|;<>()$`'):
+        return "'" + s.replace("'", "'\\''") + "'"
+    return s
+
+
+# ---------------------------------------------------------------------------
+# permissions (WP-14.4d supply-chain hardening: honest disclosure, D15)
+# ---------------------------------------------------------------------------
+def cmd_permissions(args: argparse.Namespace) -> int:
+    from .permissions import PERMISSIONS, permissions_text
+    if args.json:
+        emit_json(PERMISSIONS)
+    else:
+        print(permissions_text())
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# argparse
+# ---------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="llmt",
+        description="Find, download (BitTorrent + webseeds) and SHA-256-verify "
+                    "LLM models from the LLM Torrents catalog.",
+    )
+    p.add_argument("--version", action="version",
+                   version=f"llmt {__version__}")
+
+    def common(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("--api-base", default=None,
+                        help=f"API base URL (default: env LLMT_API_BASE or "
+                             f"{DEFAULT_API_BASE})")
+        sp.add_argument("--api-key", default=None,
+                        help="Bearer token (env LLMT_API_KEY); raises rate limits.")
+        sp.add_argument("--timeout", type=int, default=30,
+                        help="Per-request timeout in seconds (default 30).")
+        sp.add_argument("--json", action="store_true",
+                        help="Machine-readable JSON output.")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sp = sub.add_parser("search", help="Search the catalog.")
+    sp.add_argument("query", help="Search text (matched by the API's q param).")
+    sp.add_argument("--fit", default=None, help="Fit filter passed to the API.")
+    sp.add_argument("--rig", action="append", default=[],
+                    help="Rig spec as key=value (repeatable), e.g. --rig vram_gb=24.")
+    sp.add_argument("--per-page", type=int, default=24, choices=[12, 24, 48])
+    sp.add_argument("--sort", default=None)
+    common(sp)
+    sp.set_defaults(func=cmd_search)
+
+    sp = sub.add_parser("pull", help="Download + verify a model quant "
+                                     "(Ed25519-signed manifest).")
+    sp.add_argument("ref", help="slug or slug:quant (e.g. phi-4-mini:Q4_K_M).")
+    sp.add_argument("--quant", default=None,
+                    help="Override quant level (else the ref's, else best).")
+    sp.add_argument("--output", "-o", default=None, help="Output directory.")
+    sp.add_argument("--tracker", action="append", default=[],
+                    help="Extra BT tracker (repeatable).")
+    sp.add_argument("--dry-run", action="store_true",
+                    help="Print the aria2c invocation and exit (no download).")
+    common(sp)
+    sp.set_defaults(func=cmd_pull)
+
+    sp = sub.add_parser("verify",
+                        help="Re-verify downloaded files against the "
+                             "Ed25519-signed manifest (no re-download).")
+    sp.add_argument("path",
+                    help="Download directory from `llmt pull` (the outer "
+                         "directory; the inner payload directory is also "
+                         "accepted and auto-detected).")
+    sp.add_argument("ref", help="slug or slug:quant.")
+    sp.add_argument("--quant", default=None, help="Override quant level.")
+    common(sp)
+    sp.set_defaults(func=cmd_verify)
+
+    sp = sub.add_parser("seed", help="Seed an already-downloaded artifact "
+                                     "(requires a verified signed manifest).")
+    sp.add_argument("ref", help="slug or slug:quant.")
+    sp.add_argument("path", help="Directory holding the downloaded files.")
+    sp.add_argument("--quant", default=None, help="Override quant level.")
+    sp.add_argument("--tracker", action="append", default=[])
+    sp.add_argument("--dry-run", action="store_true")
+    common(sp)
+    sp.set_defaults(func=cmd_seed)
+
+    sp = sub.add_parser(
+        "scan",
+        help="Scan local model dirs; seed the ones you already have.")
+    add_scan_args(sp)
+    common(sp)
+    sp.set_defaults(func=cmd_scan)
+
+    sp = sub.add_parser(
+        "doctor",
+        help="Diagnose why your seeds aren't actually seeding "
+             "(client/port/DHT/trackers/caps/layout).")
+    add_doctor_args(sp)
+    common(sp)
+    sp.set_defaults(func=cmd_doctor)
+
+    sp = sub.add_parser(
+        "permissions",
+        help="Show exactly what llmt reads, writes, and sends. No network.")
+    sp.add_argument("--json", action="store_true",
+                    help="Machine-readable JSON output.")
+    sp.set_defaults(func=cmd_permissions)
+
+    sp = sub.add_parser(
+        "telemetry",
+        help="Opt-in seeding telemetry (OFF by default): "
+             "enable | disable | status | whoami | beat.")
+    add_telemetry_args(sp)
+
+    return p
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except LicenseGatedError as exc:
+        # D7 output: message + model_page, and ZERO artifacts.
+        if getattr(args, "json", False):
+            emit_json({
+                "error": "license_gated",
+                "slug": exc.slug,
+                "message": str(exc),
+                "model_page": exc.model_page,
+            })
+        else:
+            print(str(exc), file=sys.stderr)
+            if exc.model_page:
+                print(f"Accept the license here, then retry: {exc.model_page}",
+                      file=sys.stderr)
+            else:
+                print("Visit the model's page on the catalog to accept the "
+                      "license.", file=sys.stderr)
+        return exc.exit_code
+    except RateLimitedError as exc:
+        extra = (f" Retry after {exc.retry_after}s."
+                 if exc.retry_after else "")
+        _fail(args, str(exc) + extra, "rate_limited")
+        return exc.exit_code
+    except LlmtError as exc:
+        _fail(args, str(exc), getattr(exc, "code", None) or "error")
+        return exc.exit_code
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return 130
+
+
+def _fail(args: argparse.Namespace, message: str, code: str) -> None:
+    if getattr(args, "json", False):
+        emit_json({"error": code, "message": message})
+    else:
+        print(f"error: {message}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    sys.exit(main())