llmt-cli 0.2.0__py3-none-any.whl

llmt/models.py

@@ -0,0 +1,130 @@
+"""Model / quant resolution against the frozen API detail shape.
+
+A quant reference is ``slug`` or ``slug:quant`` where ``quant`` matches a
+quant's ``quant_level`` (case-insensitive), e.g. ``phi-4-mini:Q4_K_M``.
+
+Download-block states (from ModelDetailResource):
+    "available"                    -> full public artifacts
+    "license_acceptance_required"  -> D7 gate, only {model_page}
+    "not_available"                -> no gate-passed torrent
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .errors import (
+    LicenseGatedError,
+    NotAvailableError,
+    NotFoundError,
+)
+
+
+def parse_ref(ref: str) -> tuple[str, Optional[str]]:
+    """Split ``slug`` / ``slug:quant`` into (slug, quant_level|None)."""
+    if ":" in ref:
+        slug, quant = ref.split(":", 1)
+        return slug.strip(), (quant.strip() or None)
+    return ref.strip(), None
+
+
+def model_page_of(model: dict[str, Any]) -> Optional[str]:
+    """Best-effort model_page URL for a gated model, without fabricating one.
+
+    Prefer the acceptance_url the API supplied; else a gated quant's
+    download.model_page. Returns None if the API gave us nothing.
+    """
+    lic = model.get("license") or {}
+    if lic.get("acceptance_url"):
+        return lic["acceptance_url"]
+    for q in model.get("quants") or []:
+        dl = q.get("download") or {}
+        if dl.get("model_page"):
+            return dl["model_page"]
+    return None
+
+
+def is_gated(model: dict[str, Any]) -> bool:
+    return bool((model.get("license") or {}).get("gated"))
+
+
+def _quant_size(q: dict[str, Any]) -> int:
+    for k in ("file_size_bytes", "size_bytes", "file_size"):
+        v = q.get(k)
+        if isinstance(v, (int, float)):
+            return int(v)
+    return 0
+
+
+def select_quant(model: dict[str, Any], quant_level: Optional[str]) -> dict[str, Any]:
+    """Pick a quant from a model detail dict.
+
+    - explicit ``quant_level`` -> exact (case-insensitive) match or NotFound.
+    - otherwise "best": the largest quant that has an *available* download,
+      falling back to the largest quant overall so gate/availability errors
+      are still surfaced to the user with real context.
+    """
+    quants = model.get("quants") or []
+    slug = model.get("slug", "?")
+    if not quants:
+        raise NotFoundError(f"Model '{slug}' has no published quants.")
+
+    if quant_level is not None:
+        want = quant_level.lower()
+        for q in quants:
+            if str(q.get("quant_level", "")).lower() == want:
+                return q
+        available = ", ".join(str(q.get("quant_level")) for q in quants)
+        raise NotFoundError(
+            f"Quant '{quant_level}' not found for '{slug}'. Available: {available}"
+        )
+
+    # "best" — prefer an available quant, largest first.
+    def state(q: dict) -> str:
+        return (q.get("download") or {}).get("state", "not_available")
+
+    available = [q for q in quants if state(q) == "available"]
+    pool = available or quants
+    return max(pool, key=_quant_size)
+
+
+def require_available_download(model: dict[str, Any], quant: dict[str, Any]) -> dict[str, Any]:
+    """Return the download block, or raise the right gate/availability error.
+
+    D7: for a gated model we NEVER read artifact fields — we raise
+    LicenseGatedError carrying only the model_page pointer.
+    """
+    slug = model.get("slug", "?")
+    dl = quant.get("download") or {}
+    state = dl.get("state")
+
+    if state == "license_acceptance_required" or is_gated(model):
+        raise LicenseGatedError(slug, dl.get("model_page") or model_page_of(model))
+
+    if state == "not_available" or not state:
+        raise NotAvailableError(
+            f"No gate-passed torrent available for "
+            f"'{slug}:{quant.get('quant_level')}'."
+        )
+    if state != "available":
+        raise NotAvailableError(
+            f"'{slug}:{quant.get('quant_level')}' is not downloadable "
+            f"(state={state})."
+        )
+    return dl
+
+
+def files_of(download: dict[str, Any]) -> list[dict[str, Any]]:
+    """Normalise the download.files[] list to {path, sha256, size} dicts.
+
+    The frozen resource emits ``size_bytes``; we also tolerate ``size``.
+    """
+    out = []
+    for f in download.get("files") or []:
+        size = f.get("size_bytes", f.get("size"))
+        out.append({
+            "path": f.get("path"),
+            "sha256": (f.get("sha256") or "").lower(),
+            "size": int(size) if isinstance(size, (int, float)) else None,
+        })
+    return out

llmt/output.py

@@ -0,0 +1,51 @@
+"""Human + machine (``--json``) output helpers."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def safe_text(s: Any) -> str:
+    """Strip control characters (ANSI escapes, BEL, CR, NUL, ...) from a
+    server-derived string before printing it to a terminal, so a hostile
+    ``torrent_name`` / quant label cannot inject escape sequences. JSON output
+    does not need this (``json.dump`` already escapes control chars)."""
+    if not isinstance(s, str):
+        s = str(s)
+    return "".join(ch for ch in s if ch >= " " and ch != "\x7f")
+
+
+def emit_json(obj: Any) -> None:
+    json.dump(obj, sys.stdout, indent=2, sort_keys=False, default=str)
+    sys.stdout.write("\n")
+
+
+def human_size(n: Any) -> str:
+    if not isinstance(n, (int, float)) or n <= 0:
+        return "-"
+    units = ["B", "KB", "MB", "GB", "TB", "PB"]
+    f = float(n)
+    for u in units:
+        if f < 1024 or u == units[-1]:
+            return f"{f:.1f}{u}" if u != "B" else f"{int(f)}B"
+        f /= 1024
+    return f"{f:.1f}PB"
+
+
+def render_table(rows: list[list[str]], headers: list[str]) -> str:
+    """Render a fixed-width text table (no external deps)."""
+    cols = len(headers)
+    widths = [len(h) for h in headers]
+    for r in rows:
+        for i in range(cols):
+            widths[i] = max(widths[i], len(str(r[i])) if i < len(r) else 0)
+    line = "  ".join(h.ljust(widths[i]) for i, h in enumerate(headers))
+    sep = "  ".join("-" * widths[i] for i in range(cols))
+    out = [line, sep]
+    for r in rows:
+        out.append("  ".join(
+            str(r[i] if i < len(r) else "").ljust(widths[i]) for i in range(cols)
+        ))
+    return "\n".join(out)

llmt/permissions.py

@@ -0,0 +1,154 @@
+"""llmt's permissions statement — what it reads, writes, and sends.
+
+This is a static, honest declaration (Decision D15: brutal honesty) exposed
+as ``llmt permissions``. It requires no network and touches no files. The
+same statement lives in prose form in docs/PERMISSIONS.md; if you change one,
+change both.
+"""
+
+from __future__ import annotations
+
+# Every environment variable the shipped CLI reads, and what it does.
+# SINGLE SOURCE OF TRUTH for the env-var disclosure: the PERMISSIONS
+# statement below embeds this list, docs/PERMISSIONS.md mirrors it, and
+# tests/test_supply_chain.py greps src/ for `os.environ`/`getenv` reads and
+# fails if this dict and the code ever disagree (in either direction).
+# If you add an env read anywhere in src/llmt/, disclose it here AND in
+# docs/PERMISSIONS.md, or the suite goes red.
+ENV_VARS: dict = {
+    "LLMT_API_BASE": "catalog API base URL (same as --api-base)",
+    "LLMT_API_KEY": "optional catalog API key, sent as a bearer header "
+                    "(same as --api-key)",
+    "LLMT_QB_URL": "qBittorrent WebUI URL (same as --qb-url)",
+    "LLMT_QB_USER": "qBittorrent WebUI username (same as --qb-user)",
+    "LLMT_QB_PASS": "qBittorrent WebUI PASSWORD — a credential, read from "
+                    "your environment if set (same as --qb-pass)",
+    "LLMT_TR_URL": "Transmission RPC URL (same as --tr-url)",
+    "LLMT_TR_USER": "Transmission RPC username (same as --tr-user)",
+    "LLMT_TR_PASS": "Transmission RPC PASSWORD — a credential, read from "
+                    "your environment if set (same as --tr-pass)",
+    "LLMT_HOME": "relocates llmt's state directory (default ~/.llmt)",
+    "LLMT_TELEMETRY_ENDPOINT": "per-run telemetry endpoint override for the "
+                               "opt-in telemetry commands; never persisted",
+    "LLMT_AGENT_TOKEN": "telemetry token for `llmt telemetry enable` "
+                        "(opt-in telemetry only)",
+}
+
+PERMISSIONS: dict = {
+    "statement_version": 4,
+    "reads": [
+        {"what": "The LLM Torrents catalog API (HTTPS GET only)",
+         "detail": "Base URL you control via --api-base / LLMT_API_BASE; "
+                   "default https://llmtorrents.com/api. This includes the "
+                   "Ed25519-signed manifest for a torrent, which "
+                   "pull/verify/seed authenticate against a public key "
+                   "pinned inside the llmt package (never fetched from the "
+                   "network)."},
+        {"what": "Files and directories YOU pass on the command line",
+         "detail": "`pull -o DIR`, `verify DIR`, `seed REF DIR`: llmt reads "
+                   "those bytes to hash or seed them. It never walks "
+                   "anywhere you did not point it."},
+        {"what": "Environment variables — exactly these, nothing more: "
+                 + ", ".join(ENV_VARS) + ".",
+         "detail": "LLMT_API_BASE / LLMT_API_KEY configure the catalog API. "
+                   "The LLMT_QB_* / LLMT_TR_* variables configure your "
+                   "torrent client's WebUI connection — that INCLUDES the "
+                   "WebUI passwords (LLMT_QB_PASS, LLMT_TR_PASS) if you set "
+                   "them; command-line flags always take precedence. "
+                   "LLMT_HOME relocates ~/.llmt. LLMT_TELEMETRY_ENDPOINT and "
+                   "LLMT_AGENT_TOKEN affect only the opt-in telemetry "
+                   "commands. Beyond these, llmt reads no other "
+                   "environment variable to configure its own behavior; "
+                   "standard indirect lookups still apply, such as HOME "
+                   "to resolve `~`, PATH to locate aria2c, and the env "
+                   "vars the `requests` library honors (proxy, CA-bundle, "
+                   "and netrc variables), as with any HTTP client."},
+        {"what": "Directories you point `llmt scan` at (read-only)",
+         "detail": "Hashes candidate model files where you say to look."},
+        {"what": "Your torrent client's WebUI on localhost",
+         "detail": "Only if you configure it, only on addresses you supply, "
+                   "with credentials you supply — to add torrents and "
+                   "trigger rechecks."},
+    ],
+    "writes": [
+        {"what": "Downloaded model files",
+         "detail": "Only into the output directory you choose for "
+                   "`llmt pull` (default: current directory)."},
+        {"what": "Link farms under ~/.llmt/seeding-layouts/",
+         "detail": "Hardlinks/symlinks pointing at YOUR existing files so a "
+                   "client can seed them in place. Never copies, never moves, "
+                   "never modifies your originals."},
+        {"what": "Its own state under ~/.llmt/",
+         "detail": "An optional config file (~/.llmt/config.json) and, ONLY if "
+                   "you opt into telemetry, the telemetry token "
+                   "(~/.llmt/agent-token, mode 0600) plus a local artifact "
+                   "hash cache. Nothing here is created until you set a config "
+                   "value or run `llmt telemetry enable`."},
+    ],
+    "sends": [
+        {"what": "Catalog API requests",
+         "detail": "Your search text, model slugs you request, the info "
+                   "hashes of torrents whose signed manifests it fetches "
+                   "(pull/verify/seed), and — only if you set one — your "
+                   "API key as a bearer header."},
+        {"what": "SHA-256 hashes to the artifact-lookup endpoint",
+         "detail": "When `llmt scan` runs, it sends ONLY the SHA-256 hashes "
+                   "of files it scanned — never paths, never filenames, "
+                   "never directory listings, never machine info."},
+        {"what": "BitTorrent traffic (via aria2c, a separate program)",
+         "detail": "`pull`/`seed` hand the magnet + webseeds to aria2c; your "
+                   "IP is visible to trackers/peers exactly as with any "
+                   "torrent client."},
+        {"what": "Opt-in seeding telemetry — OFF by default, only after "
+                 "`llmt telemetry enable`",
+         "detail": "When (and only when) you explicitly opt in, heartbeats "
+                   "send your torrents' infohashes/names/states/progress, the "
+                   "SHA-256s of artifacts you seed, and server-challenged "
+                   "byte-range hashes, plus your telemetry token as a bearer "
+                   "header — to the telemetry endpoint you configure. NEVER "
+                   "file paths, scan data, or machine info. Revoke any time "
+                   "with `llmt telemetry disable` (which deletes the token); "
+                   "view/delete server-side data on the website."},
+    ],
+    "environment": [
+        {"name": name, "why": why} for name, why in ENV_VARS.items()
+    ],
+    "never": [
+        "No HIDDEN telemetry: analytics, crash reporting and usage pings do "
+        "not exist. Seeding telemetry is a SEPARATE, explicit, off-by-default, "
+        "revocable opt-in (`llmt telemetry enable`) and never runs without "
+        "your consent; even then it sends only infohashes/names/states/"
+        "progress + artifact SHA-256s + challenge range hashes — never paths, "
+        "scan data, or machine fingerprints.",
+        "No update checks and NO self-update mechanism: llmt never replaces "
+        "its own code. You update it with pip or your package manager.",
+        "Never sends file paths, filenames, directory listings, hardware "
+        "or OS fingerprints.",
+        "Never reads or scans anything you did not explicitly point it at.",
+        "Never runs with elevated privileges or asks you to.",
+    ],
+}
+
+
+def permissions_text() -> str:
+    """Human-readable rendering of :data:`PERMISSIONS`."""
+    out = ["llmt permissions — what this tool reads, writes and sends",
+           "=" * 58, ""]
+    sections = [("READS", "reads"), ("WRITES", "writes"), ("SENDS", "sends")]
+    for title, key in sections:
+        out.append(title)
+        for item in PERMISSIONS[key]:
+            tag = "  "
+            out.append(f"{tag}* {item['what']}")
+            out.append(f"      {item['detail']}")
+        out.append("")
+    out.append("ENVIRONMENT VARIABLES READ (the complete list)")
+    for name, why in ENV_VARS.items():
+        out.append(f"  * {name}: {why}")
+    out.append("")
+    out.append("NEVER")
+    for line in PERMISSIONS["never"]:
+        out.append(f"  * {line}")
+    out.append("")
+    out.append("Full prose version: docs/PERMISSIONS.md in the source tree.")
+    return "\n".join(out)