llmt-cli 0.2.0__py3-none-any.whl

llmt/telemetry/wire.py

@@ -0,0 +1,194 @@
+"""Client side of the FROZEN Agent Write-API contract v1 (WP-14.4-T).
+
+Namespace: ``<endpoint>/agent/v1``. Auth: ``Authorization: Bearer llmta_...``
+on every request. This module speaks EXACTLY the frozen wire and no more:
+
+  * POST /agent/v1/heartbeats     -> accepted / unmatched / challenges
+  * POST /agent/v1/challenges/{nonce}  -> pass|fail|expired|already-used
+  * GET  /agent/v1/me             -> user / scopes / telemetry_consent
+
+Status handling: 401 -> TelemetryAuthError, 403 -> TelemetryScopeError,
+429 -> RateLimitedError honoring ``retry_after_seconds`` (body) or Retry-After
+(header). Unknown RESPONSE fields are ignored by callers; we send exactly the
+frozen request fields (the server 422s unknown request fields).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+from urllib.parse import quote, urlsplit
+
+import requests
+
+from ..errors import ApiError, RateLimitedError, TimeoutErrorLlmt
+from .errors import TelemetryAuthError, TelemetryConfigError, TelemetryScopeError
+
+_TOKEN_RE = re.compile(r"^llmta_[A-Za-z0-9_-]{40,64}$")
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+_NONCE_RE = re.compile(r"^[A-Za-z0-9_.\-]{1,256}$")
+
+
+def looks_like_token(token: object) -> bool:
+    """Best-effort shape check for ``llmta_`` + base64url(32 bytes).
+
+    32 bytes base64url is 43 chars (unpadded); we allow a small range to be
+    tolerant of padding/format drift. Used only for a friendly enable-time
+    warning — the server is the authority (a bad token 401s).
+    """
+    return isinstance(token, str) and bool(_TOKEN_RE.match(token))
+
+
+def _require_https(base: str) -> None:
+    parts = urlsplit(base)
+    host = (parts.hostname or "").lower()
+    if parts.scheme == "https":
+        return
+    if parts.scheme == "http" and host in _LOOPBACK:
+        return
+    raise TelemetryConfigError(
+        f"refusing to send telemetry over a non-HTTPS endpoint: {base!r}. "
+        f"Use an https:// endpoint (MITM/token-theft defense).")
+
+
+def clamp_retry_after(seconds: Optional[int],
+                      max_seconds: int) -> Optional[int]:
+    """Clamp a server-supplied 429 backoff to [0, max_seconds] so a hostile
+    huge value cannot make a --loop sleep effectively forever."""
+    if seconds is None:
+        return None
+    if max_seconds < 0:
+        max_seconds = 0
+    return max(0, min(int(seconds), int(max_seconds)))
+
+
+def _retry_after(resp: "requests.Response", payload: Any) -> Optional[int]:
+    # Body wins if present and sane, else the Retry-After header.
+    if isinstance(payload, dict):
+        ra = payload.get("retry_after_seconds")
+        if isinstance(ra, bool):
+            ra = None
+        if isinstance(ra, (int, float)) and ra >= 0:
+            return int(ra)
+    hdr = resp.headers.get("Retry-After")
+    if hdr is not None:
+        try:
+            return max(0, int(hdr))
+        except (ValueError, TypeError):
+            return None
+    return None
+
+
+class AgentClient:
+    """Thin, dependency-light wrapper over the agent write API."""
+
+    def __init__(self, endpoint: str, token: str, *, timeout: int = 30,
+                 session: Optional[requests.Session] = None):
+        endpoint = (endpoint or "").rstrip("/")
+        if not endpoint:
+            raise TelemetryConfigError("no telemetry endpoint configured.")
+        self.endpoint = endpoint
+        self.base = endpoint + "/agent/v1"
+        _require_https(self.base)
+        if not token:
+            raise TelemetryConfigError(
+                "no telemetry token stored; run `llmt telemetry enable`.")
+        self.token = token
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    # ---- low level ------------------------------------------------------
+    def _headers(self, *, body: bool = False) -> dict[str, str]:
+        h = {
+            "Accept": "application/json",
+            "User-Agent": "llmt-cli",
+            "Authorization": f"Bearer {self.token}",
+        }
+        if body:
+            h["Content-Type"] = "application/json"
+        return h
+
+    def _request(self, method: str, path: str,
+                 json_body: Optional[dict] = None) -> dict[str, Any]:
+        url = f"{self.base}/{path.lstrip('/')}"
+        try:
+            resp = self.session.request(
+                method, url, json=json_body,
+                headers=self._headers(body=json_body is not None),
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.Timeout as exc:
+            raise TimeoutErrorLlmt(
+                f"telemetry request timed out after {self.timeout}s: {url}"
+            ) from exc
+        except requests.RequestException as exc:
+            raise ApiError(f"telemetry request failed: {exc}") from exc
+        return self._handle(resp, url)
+
+    def _handle(self, resp: "requests.Response", url: str) -> dict[str, Any]:
+        payload: Any = None
+        try:
+            payload = resp.json()
+        except ValueError:
+            payload = None
+        msg = None
+        if isinstance(payload, dict):
+            err = payload.get("error")
+            if isinstance(err, dict):
+                msg = err.get("message")
+            elif isinstance(err, str):
+                msg = err
+            msg = msg or payload.get("message")
+
+        sc = resp.status_code
+        if 200 <= sc < 300:
+            return payload if isinstance(payload, dict) else {}
+        if sc == 401:
+            raise TelemetryAuthError(
+                msg or "telemetry token missing/unknown/revoked (401). "
+                "Re-issue a token on the website and run "
+                "`llmt telemetry enable` again.")
+        if sc == 403:
+            raise TelemetryScopeError(
+                msg or "telemetry token lacks the telemetry:write scope (403).")
+        if sc == 429:
+            raise RateLimitedError(
+                msg or "telemetry rate-limited (429).",
+                retry_after=_retry_after(resp, payload),
+                code="rate_limited", status=429,
+            )
+        if sc == 422:
+            raise ApiError(msg or "telemetry request rejected (422).",
+                           code="unprocessable", status=422)
+        if 300 <= sc < 400:
+            raise ApiError(
+                f"telemetry endpoint returned a redirect (HTTP {sc}); refusing "
+                f"to re-send heartbeat data to "
+                f"{resp.headers.get('Location') or 'another host'}. "
+                f"Point telemetry.endpoint at the final HTTPS URL.",
+                code="redirect", status=sc)
+        raise ApiError(
+            msg or f"unexpected telemetry response (HTTP {sc}).", status=sc)
+
+    # ---- endpoints ------------------------------------------------------
+    def heartbeat(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST /agent/v1/heartbeats. ``payload`` MUST already be the exact
+        frozen wire object (see beat.build_heartbeat_payload)."""
+        return self._request("POST", "/heartbeats", json_body=payload)
+
+    def answer_challenge(self, nonce: str, hash_hex: str) -> str:
+        """POST /agent/v1/challenges/{nonce} with {"hash": hex64}. Returns the
+        result string ("pass"|"fail"|"expired"|"already-used")."""
+        if not isinstance(nonce, str) or not _NONCE_RE.match(nonce):
+            raise ApiError("refusing a malformed challenge nonce.")
+        resp = self._request(
+            "POST", f"/challenges/{quote(nonce, safe='')}",
+            json_body={"hash": hash_hex},
+        )
+        result = resp.get("result")
+        return result if isinstance(result, str) else "unknown"
+
+    def me(self) -> dict[str, Any]:
+        """GET /agent/v1/me — identity + scopes + telemetry_consent."""
+        return self._request("GET", "/me")

llmt/verify.py

@@ -0,0 +1,129 @@
+"""SHA-256 verification — the core trust feature of llmt.
+
+Given a base directory and a ``files[]`` list (each entry has a ``path``
+and an expected ``sha256`` — since Fix M2 the CLI sources these from the
+Ed25519-VERIFIED manifest, see llmt.manifest), we hash every file on disk in streaming
+64 KiB chunks and compare, constant work per byte, no whole-file buffering.
+
+A single mismatch, a missing file, or a wrong size is a FAILURE. ``pull`` and
+``verify`` both exit non-zero when any file fails — that non-zero exit is the
+signal an automated pipeline keys on.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .layout import LayoutSafetyError, safe_join, sanitize_relpath
+
+_CHUNK = 64 * 1024
+
+
+def sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(_CHUNK), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+@dataclass
+class FileResult:
+    path: str
+    expected: str
+    actual: Optional[str]
+    size_expected: Optional[int]
+    size_actual: Optional[int]
+    status: str  # "ok" | "mismatch" | "missing" | "size_mismatch" | "no_hash" | "unsafe_path"
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "ok"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "status": self.status,
+            "expected_sha256": self.expected,
+            "actual_sha256": self.actual,
+            "expected_size": self.size_expected,
+            "actual_size": self.size_actual,
+        }
+
+
+def resolve_catalog_path(base_dir: str, rel: str) -> str:
+    """Resolve an untrusted catalog ``files[].path`` strictly under ``base_dir``.
+
+    Catalog paths are relative by contract. A hostile API response must not be
+    able to point verification at a file OUTSIDE the target directory (e.g.
+    ``/etc/hostname`` or ``../../secret``) — hashing such a file and printing
+    "VERIFIED OK" would attest to bytes the user never downloaded. Absolute
+    paths, ``..`` traversal, and anything else that resolves outside
+    ``base_dir`` raise :class:`~llmt.errors.LayoutSafetyError` (fail closed).
+    """
+    if rel.startswith(("/", "\\")) or os.path.isabs(rel) or (
+            len(rel) >= 2 and rel[1] == ":"):
+        raise LayoutSafetyError(f"absolute catalog path rejected: {rel!r}")
+    segments = sanitize_relpath(rel)   # rejects '..', NULs, ':', control chars
+    return safe_join(os.path.abspath(base_dir), segments)
+
+
+def verify_files(base_dir: str, files: list[dict[str, Any]]) -> list[FileResult]:
+    """Verify each catalog file entry against disk under ``base_dir``."""
+    results: list[FileResult] = []
+    for f in files:
+        rel = f.get("path")
+        expected = (f.get("sha256") or "").lower()
+        size_expected = f.get("size")
+
+        full: Optional[str] = None
+        if rel:
+            try:
+                full = resolve_catalog_path(base_dir, rel)
+            except LayoutSafetyError:
+                # Fail closed: a hostile catalog path must never make us hash
+                # (let alone attest) a file outside base_dir.
+                results.append(FileResult(
+                    path=rel, expected=expected, actual=None,
+                    size_expected=size_expected, size_actual=None,
+                    status="unsafe_path",
+                ))
+                continue
+
+        if full is None or not os.path.isfile(full):
+            results.append(FileResult(
+                path=rel, expected=expected, actual=None,
+                size_expected=size_expected, size_actual=None, status="missing",
+            ))
+            continue
+
+        size_actual = os.path.getsize(full)
+        if not expected:
+            # The API gave us no hash — we cannot vouch for it. Report loudly
+            # rather than silently pass (never fabricate a "safe" verdict).
+            results.append(FileResult(
+                path=rel, expected="", actual=sha256_file(full),
+                size_expected=size_expected, size_actual=size_actual,
+                status="no_hash",
+            ))
+            continue
+
+        actual = sha256_file(full)
+        if actual != expected:
+            status = "mismatch"
+        elif size_expected is not None and size_actual != size_expected:
+            status = "size_mismatch"
+        else:
+            status = "ok"
+        results.append(FileResult(
+            path=rel, expected=expected, actual=actual,
+            size_expected=size_expected, size_actual=size_actual, status=status,
+        ))
+    return results
+
+
+def all_ok(results: list[FileResult]) -> bool:
+    return bool(results) and all(r.ok for r in results)

llmt_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: llmt-cli
+Version: 0.2.0
+Summary: Find, download (over BitTorrent + webseeds), and SHA-256-verify LLM models from the LLM Torrents catalog.
+Author: LLM Torrents
+License: MIT
+Project-URL: Homepage, https://llmtorrents.com
+Project-URL: Source, https://llmtorrents.com
+Keywords: llm,torrent,bittorrent,webseed,sha256,ed25519,models,aria2
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: PyNaCl>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: requests-mock>=1.9; extra == "dev"
+Dynamic: license-file
+
+# llmt — LLM Torrents command-line client
+
+`llmt` finds LLM models in the [LLM Torrents](https://llmtorrents.com) catalog,
+downloads them over **BitTorrent with HTTP webseeds**, and — the point of the
+whole thing — **verifies what you got**: it fetches the catalog's
+**Ed25519-signed manifest** for the torrent, checks the signature against a
+public key **pinned inside this package** (not fetched from the network), and
+then verifies every downloaded file's SHA-256 against that verified manifest.
+If a byte is wrong — or the manifest cannot be authenticated — `llmt` tells
+you and exits non-zero.
+
+## Install
+
+```bash
+pip install llmt-cli      # from PyPI (once published; installs the `llmt` command)
+# or, from a checkout:
+pip install -e .
+```
+
+Requires Python ≥ 3.9 and [`aria2c`](https://aria2.github.io/) on your `PATH`
+for downloading/seeding (`apt install aria2`, `brew install aria2`, …). If
+`aria2c` is missing, `llmt` prints a clear message instead of crashing.
+
+## Security & supply chain
+
+`llmt` is high-trust software (it hashes your disk and drives a torrent
+client), so it is built to be audited, not trusted:
+
+- Catalog manifests are **Ed25519-signed**; `pull`/`verify`/`seed` verify the
+  signature against the public key **pinned in the package**
+  (`llmt/data/manifest-pubkey.json`) — the trust root ships with the code and
+  is never fetched from the network at runtime. A manifest that cannot be
+  authenticated (unreachable, malformed, bad signature, wrong/rotated key, or
+  disagreeing with the catalog) is **never reported as verified**: distinct
+  error, exit `15`. Key rotation ships as a new `llmt` release.
+- `llmt permissions` prints exactly what the tool reads, writes, and sends
+  (no telemetry, **no self-update** — enforced by unit test). Prose version:
+  [docs/PERMISSIONS.md](docs/PERMISSIONS.md).
+- Dependencies are pinned: `pip install llmt-cli -c constraints.txt`, or
+  fully hash-verified in two steps (the lock file covers the dependency
+  closure only — `llmt` itself is not in it, so install it separately):
+  `pip install --require-hashes -r requirements.lock && pip install --no-deps .`
+- Releases ship a `SHA256SUMS` file (checksums published on
+  llmtorrents.com); build + signing process: [docs/RELEASING.md](docs/RELEASING.md).
+- Vulnerability reports: [SECURITY.md](SECURITY.md).
+- Docker image (pinned base, non-root) and homelab recipes:
+  [docs/recipes/](docs/recipes/).
+
+## Usage
+
+```bash
+llmt search "llama"                       # readable table of matches
+llmt search "qwen" --fit --rig vram_gb=24 # fit verdict for your rig
+llmt search "phi" --json                  # machine-readable
+
+llmt pull microsoft-phi-4-mini            # best quant -> download -> verify
+llmt pull microsoft-phi-4-mini:Q4_K_M     # a specific quant
+llmt pull acme-tiny-1b --dry-run          # show the exact aria2c command
+
+llmt verify ./acme-tiny-1b-Q4_K_M acme-tiny-1b:Q4_K_M   # re-check, no download
+llmt seed acme-tiny-1b:Q4_K_M ./acme-tiny-1b-Q4_K_M     # help the swarm
+```
+
+Global flags on every command: `--json`, `--api-base`, `--api-key`,
+`--timeout`. Configure via env: `LLMT_API_BASE`, `LLMT_API_KEY`
+(the complete list of every env var `llmt` reads is in
+[docs/PERMISSIONS.md](docs/PERMISSIONS.md) and `llmt permissions`).
+An API key is optional and only **raises your rate limits** — all reads are
+public.
+
+## The trust story (signed manifest + SHA-256)
+
+A torrent's own piece hashes only prove the bytes match *that* `.torrent`.
+They don't prove the `.torrent` describes the model the catalog vouched for
+— and TLS alone only proves who you *talked to*, not that the file list is
+the one the catalog *signed*. `llmt` closes both gaps:
+
+1. **The Ed25519-signed manifest is the source of truth.** For a non-gated
+   model, `llmt` fetches the torrent's manifest
+   (`GET /api/manifests/{info_hash}`) and **verifies its detached Ed25519
+   signature** against the public key pinned inside this package
+   (`llmt/data/manifest-pubkey.json`, per the open
+   [manifest spec](https://llmtorrents.com/schema/manifest-v0.1.0.json)).
+   It also checks that the signed document actually names the torrent being
+   verified, and that the API's `download.files[]` block agrees with the
+   signed manifest.
+2. **After the download**, `llmt` streams each file through SHA-256 (64 KiB
+   chunks, no whole-file buffering) and compares byte-for-byte against the
+   **verified manifest's** hash. This is a real, independent check — not
+   aria2c's piece check.
+3. **Any mismatch, missing file, or wrong size fails the run** and `llmt`
+   exits non-zero (`3`). A tampered or truncated file cannot pass silently.
+   A file for which no hash was supplied is flagged `NO-HASH`, never waved
+   through.
+4. **An unauthenticatable manifest fails the run before any hashing** —
+   unreachable endpoint (e.g. offline), malformed document, invalid
+   signature, unknown/rotated signing key, wrong torrent, or a
+   catalog/manifest disagreement each produce a distinct error and exit
+   `15`. `llmt` never silently falls back to trusting unsigned hashes over
+   TLS. (If the key was rotated, upgrading to the newest `llmt` release
+   picks up the new pinned key.)
+5. **`llmt verify`** re-runs exactly this check on already-downloaded files
+   — including the manifest signature check, so it needs the catalog API to
+   be reachable; there is no offline "verified". `llmt seed` refuses to
+   seed a torrent whose manifest cannot be authenticated.
+
+Because a wrong file trips a non-zero exit, `llmt pull` / `llmt verify` drop
+straight into a pipeline: if it exits `0`, every file matched the
+Ed25519-verified manifest.
+
+## License-gated models (why some models won't download)
+
+Some models are distributed under a click-through license. For those, the
+catalog API serves **no download artifacts at all** — no magnet, no hashes, no
+file list. `llmt` detects this and tells you to accept the license on the
+model's page first:
+
+```
+$ llmt pull meta-llama-llama-3-3-70b-instruct
+'meta-llama-llama-3-3-70b-instruct' is license-gated. The catalog API does not
+serve download artifacts for gated models.
+Accept the license here, then retry: https://llmtorrents.com/models/meta-llama-llama-3-3-70b-instruct
+```
+
+`llmt` will never fabricate a magnet or hash to work around a gate.
+
+## How the download works (aria2c + webseeds)
+
+`llmt` delegates the transfer to `aria2c`, passing the catalog's magnet URI
+plus every webseed URL as trailing HTTP URIs, so aria2c uses the project's
+HTTP mirrors as web-seeds alongside the BitTorrent swarm. Roughly:
+
+```
+aria2c --dir <out> --enable-dht=true --bt-enable-lpd=true \
+       --check-integrity=true --max-connection-per-server=8 --seed-time=0 \
+       [--bt-tracker <tracker> ...] \
+       <magnet> <webseed-url-1> <webseed-url-2> ...
+```
+
+Use `llmt pull ... --dry-run` to print the exact command for your model.
+
+### Known webseed quirks (why aria2c may exit non-zero on a good download)
+
+Both HTTP origins serve the model files but **403 the bare base URL**
+(directory listings are disabled by design), and hybrid v1+v2 torrents
+contain BEP-47 `.pad` entries that **404 on the HTTP mirrors** (often seen as
+a "stall" at 98-99% in aria2c's progress summary). Either can make `aria2c`
+exit non-zero (e.g. code 22) even though every payload byte arrived.
+
+`llmt pull` handles this: when aria2c exits non-zero it checks that every
+expected file is present on disk at its expected size. If so, it notes the
+quirk on stderr and proceeds straight to the full SHA-256 verification — the
+hash check against the signed manifest, not aria2c's exit code, is the trust
+signal. If files are missing or the wrong size, the download really did fail
+and `llmt` exits `10` loudly.
+
+`llmt verify <dir> <ref>` accepts either the **outer** download directory
+(the one `pull` created) or the **inner** payload directory the torrent
+unpacked inside it — it detects which you passed. If it can't find the files
+at all, it tells you exactly which directory to pass.
+
+## Seeding your existing models (the layout mapper)
+
+SHA-256 tells you a file *is* the right bytes, but a BitTorrent client won't
+seed those bytes unless they appear at the exact path the torrent expects,
+under the torrent's root folder. Your model lives at
+`/models/qwen3-30b/model.gguf`; the torrent wants
+`qwen3-30b-a3b-q4-k-m/Qwen3-30B-A3B-Q4_K_M.gguf`. The layout mapper plans how to
+present your existing file to the client **without moving or copying it**.
+
+- **Direct-use:** if your file already sits at the expected relative path, the
+  plan is just "add the torrent with this save path" — no links at all.
+- **Link farm (default for mismatched layouts):** the mapper builds a tiny tree
+  under `~/.llmt/seeding-layouts/<torrent-root>/…` whose entries are hard/sym
+  **links** back to your real file. Your model folder stays your model folder;
+  the farm is just a set of pointers the client can follow. Save path is the
+  layouts dir; the client rechecks, sees 100%, and seeds. Model weights are
+  never re-downloaded and nothing is duplicated on disk. One honest caveat for
+  multi-file torrents you hold only partially: small companion files
+  (license/README-class, at most 10 MiB total per torrent) may be fetched by
+  your client, and `llmt scan` prints a notice naming them and where they land
+  first; any larger missing file is marked "do not download" in your client
+  before the torrent can resume, with a warning that it will seed only what
+  you have and show as incomplete.
+
+Hardlinks are preferred whenever the file and the farm are on the same
+filesystem/volume — they need no privileges and every client follows them. A
+symlink is the labelled cross-volume fallback.
+
+| Platform | Same volume | Cross volume |
+| --- | --- | --- |
+| Linux / macOS | hardlink | symlink |
+| Windows | hardlink (same drive, no admin) | symlink — needs **Administrator or Developer Mode** (NTFS junctions redirect directories only, not files) |
+
+The client must **force-recheck** after adding so it verifies the linked bytes
+and reaches 100%. The mapper refuses any path that would escape the layouts dir
+(`..`, absolute/drive-letter/UNC tricks, reserved names, null bytes) and never
+silently replaces an existing link that points somewhere else.
+
+**Dockerized or remote clients (seedbox / unRAID):** a qBittorrent or
+Transmission running in a container only sees its own **mounted volumes**, not
+host paths like `~/.llmt/seeding-layouts`. If the link farm lives on a path the
+client cannot see, its force-recheck reads **0%** and `llmt scan` **fails
+closed** (it never resumes an unverified torrent). Point the farm at a directory
+the client has mounted with `--layout-base`, e.g.
+`llmt scan --layout-base /mnt/user/appdata/qbittorrent/llmt-layouts`. `llmt
+scan` also prints an early advisory when it detects the client's own default
+save path does not exist on the machine llmt is running on (a sign the two are
+on different filesystems), and `llmt doctor` reports a `layout-base-visible`
+check that WARNs in the same situation.
+
+## Opt-in seeding telemetry (off by default)
+
+Telemetry lets the LLM Torrents site **credit you for the artifacts you
+seed**. It is a *separate, explicit, off-by-default, revocable* opt-in — it
+never runs until you turn it on, and it never sends file paths or scan data.
+
+```bash
+llmt telemetry enable            # prints the exact consent statement, then
+                                 # prompts for your token (from the website)
+llmt telemetry enable --yes --token llmta_xx…   # non-interactive (scripts)
+llmt telemetry status            # consent state, token presence, last beat
+llmt telemetry whoami            # who the stored token belongs to (GET /me)
+llmt telemetry beat --qb-url http://localhost:8080   # send one heartbeat
+llmt telemetry beat --loop       # keep beating every 15 min (or --interval N)
+llmt telemetry disable           # stop sending AND delete the stored token
+```
+
+`beat` reads the torrents from your client (`--qb-url`/`--tr-url` or
+`LLMT_QB_URL`/`LLMT_TR_URL`, same flags as `scan`/`doctor`), reports each
+torrent's infohashes (v1 **and** v2 for hybrid torrents), name, state and
+progress plus the SHA-256s of the artifacts you hold, and answers any
+possession challenges the server issues by hashing a server-chosen byte range
+of the local file. Run it from `cron` (the primary mode) or with `--loop`.
+
+**What is sent:** torrent infohashes/names/states/progress, artifact
+SHA-256s, and challenge byte-range hashes — nothing else.
+**What is never sent:** file paths, filenames, scan data, or machine info.
+The token is stored at `~/.llmt/agent-token` (mode `0600`) and is never
+printed after it is saved. View or delete your server-side data on the
+website (Account -> Telemetry). See [docs/PERMISSIONS.md](docs/PERMISSIONS.md)
+and `llmt permissions` for the full statement.
+
+Config keys (in `~/.llmt/config.json`, all under `telemetry`):
+`enabled` (default `false`), `endpoint` (default `https://llmtorrents.com`),
+`interval_minutes` (`15`), `max_torrents_per_heartbeat` (`500`),
+`report_artifacts` (`true`), `token_path`, `challenge_chunk_size`.
+Override the endpoint per-run with `--endpoint` or `LLMT_TELEMETRY_ENDPOINT`.
+
+## Exit codes
+
+| code | meaning |
+|------|---------|
+| 0 | success / all files verified |
+| 2 | generic API error (incl. 403) |
+| 3 | **SHA-256 verification failed** |
+| 4 | not found (404) |
+| 5 | rate limited (429; respects `Retry-After`) |
+| 6 | request timed out |
+| 7 | model is license-gated (D7) |
+| 8 | no gate-passed torrent available |
+| 9 | `aria2c` not installed |
+| 10 | `aria2c` failed and the download is incomplete |
+| 14 | torrent-client add/connection failed |
+| 15 | **manifest unverifiable** (fetch failed/offline, malformed, bad signature, wrong/rotated key, wrong torrent, or catalog/manifest mismatch) — nothing was verified |
+| 20 | telemetry error (generic / disabled) |
+| 21 | telemetry token missing/unknown/revoked (401) |
+| 22 | telemetry token lacks `telemetry:write` scope (403) |
+| 23 | telemetry config error (no token / bad endpoint) |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -m "not live"   # offline unit suite (mocked API)
+pytest -m live         # read-only smoke calls to the real API
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

llmt_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+llmt/__init__.py,sha256=3xJ4TYgXuGtJIq8DeJLP7WS-MCq6K9vDN8OIJKgtKWs,190
+llmt/api.py,sha256=G0afRrZtaCb_Uk2G72lm6n4AzF9-dCbcw3156xflp2c,5031
+llmt/cli.py,sha256=T9BejN8hN_lU5bkyjqN4AgRCdz_Kj0p6NjnF6lysBdg,21950
+llmt/clients.py,sha256=cuEEY3DsGo8daWBcq8F7FiK1uRcoLkYH1WvbXgaSQA8,65824
+llmt/doctor.py,sha256=SElmJ03LZEftMMh9a2o1DAgmmBxSqgqxq1oK6l6-Zas,42487
+llmt/doctorcmd.py,sha256=M_2QRr_YcU47zje--vkv4r_fW1TkFXL70sOokb1GtmI,5770
+llmt/download.py,sha256=Dujd3E52ftZhurj7EmhptiD-X28WyaGA1crTzODSdNM,13325
+llmt/errors.py,sha256=hP8cCUMCj45PnBMUULXper_7hym5GFa71samYe4YJYg,3901
+llmt/layout.py,sha256=Qo0_17GODs8-wR16EDECO6hVI7bSxU8NsHI6SZDVfuE,27408
+llmt/manifest.py,sha256=G323gyJqIgIetxW7RyGazn7XrjVVISQ0ukv6wi3Jxeo,13063
+llmt/matcher.py,sha256=maY5pjOhy1ocP-FJ1oo9RIBXAsixc36Lt8nItV_WeZ4,13859
+llmt/models.py,sha256=fTkfeKbjC7AKpvGCoH30AujUkySuhSJMW1mQ8qS2ZtQ,4501
+llmt/output.py,sha256=isQIQGclRAldnmYdXpu7cDtwrzoVyCjS816UkyyXmW8,1683
+llmt/permissions.py,sha256=VHtcZGyCoyKxs7vPG-2p3A_3ZQriMYHAF8-gmDoqY_Y,8599
+llmt/scancmd.py,sha256=IXzH6f8Y5SK3VKyChRy5syjVRrDg4t5joqwhKXHtk8Y,25228
+llmt/scanner.py,sha256=ehmoy_dfhlG5acWyRIlIYaR3V-oe1wbAHQCTUAKKciE,12606
+llmt/verify.py,sha256=-oiaU4VVicnTENQabIOkVvAm0B4ab3wBlqZrvSl6P7o,4755
+llmt/data/manifest-pubkey.json,sha256=jkJQjfy7xZY27CtoOiQa80zXkq4ZThxVjBZosSH5zkM,826
+llmt/telemetry/__init__.py,sha256=P-CiNwRgLgRPCt5tuV522_FDX8kshmkI8wgBmfteQJ0,614
+llmt/telemetry/artifacts.py,sha256=o2lGk_kzZs5gcaE-SHjVR504THJMh0Yydl8TYyLqn-I,7700
+llmt/telemetry/beat.py,sha256=jp4imwu2XFNpPLCE50j-9ckXw1glOV-nd4MrlzhPUIY,7910
+llmt/telemetry/cmd.py,sha256=CUOkm-zcn72jkCMxftJLvJJjns7V9kk6C9qb-_NKwhU,14386
+llmt/telemetry/collect.py,sha256=C-AONmeiehTeCA_y-vsw200nnIv7StJwr7-ZtUKjoSs,9379
+llmt/telemetry/config.py,sha256=hpH57eTZF-b8TgGxS7ZK_YN6SyOoTypXdsJa8j5r1fM,8285
+llmt/telemetry/consent.py,sha256=5UqX7QQiG49037EXxZz_OQtgdnPONPhwnyp11kES_2E,2302
+llmt/telemetry/errors.py,sha256=9doXH9YOBHVXa62BwhzB6v91WJSEvlwtInDBGoC4jGA,1099
+llmt/telemetry/wire.py,sha256=6DhC8G43nC-QWGpPknwxepgfniEy7RCjaejvUxfqhy4,7772
+llmt_cli-0.2.0.dist-info/licenses/LICENSE,sha256=eg7KBPmi0icU5gbQ74lXkvP4gELLCv6viKNYGIjCJig,1069
+llmt_cli-0.2.0.dist-info/METADATA,sha256=Jv1iLfUgWqHKU7ZZ08bbDu6MTjE48VSZWi1agFNZBzY,15276
+llmt_cli-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+llmt_cli-0.2.0.dist-info/entry_points.txt,sha256=TrwRcAeqlhMTLb27G4J5UQonZ_CRmMCFhoel5lAyz2E,39
+llmt_cli-0.2.0.dist-info/top_level.txt,sha256=-v9nLTNARRXP6yaL6tfqfAYvftCYThx6dsUHE2CVuRk,5
+llmt_cli-0.2.0.dist-info/RECORD,,

llmt_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

llmt_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+llmt = llmt.cli:main